Commands

BespokeFit provides a full command line interface to its major features under the alias openff-bespoke. The CLI is organised into sub-commands similar to conda, GROMACS, git and apt. This CLI is self-documenting via the --help switch which is available on any subcommand:

openff-bespoke --help
openff-bespoke executor launch --help

The executor can also be configured via environment variables.

See the quick start guide for examples of using the CLI.

openff-bespoke

The root group for all CLI commands.

openff-bespoke [OPTIONS] COMMAND [ARGS]...

cache

Commands to manually update the qc data cache.

openff-bespoke cache [OPTIONS] COMMAND [ARGS]...

update

The main worker function which updates the redis cache with qcsubmit results objects.

openff-bespoke cache update [OPTIONS]

Options

--file <input_file_path>: The serialised openff-qcsubmit file.

--qcf-dataset <qcf_dataset_name>: The name of the dataset in QCFractal to cache locally.

--qcf-datatype <qcf_datatype>

The type of dataset to cache.

Default: torsion
Options: torsion | optimization | hessian

--qcf-address <qcf_address>

The address of the QCFractal server to pull the dataset from.

Default: api.qcarchive.molssi.org:443

--qcf-config <qcf_config>: The path to a QCFractal config file containing the address username and password.

--qcf-spec <qcf_specification>

The name of the calculation specification in QCFractal.

Default: default

--launch-redis, --no-launch-redis

Whether to launch a redis server if an already running one cannot be found.

Default: True

combine

Combine force fields from local files and task ids.

openff-bespoke combine [OPTIONS]

Options

--output <output_file>: Required The name of the file the combined force field should be wrote to.

--ff <force_field_files>: The file name of any local force fields to include in the combined force field.

--id <task_ids>: The task ids from which the final force field should be added to the combined force field.

executor

Commands for interacting with a bespoke executor.

openff-bespoke executor [OPTIONS] COMMAND [ARGS]...

launch

Launch a bespoke executor.

openff-bespoke executor launch [OPTIONS]

Options

--directory <directory>

Required The directory to store any working and log files in

Default: bespoke-executor

--n-fragmenter-workers <n_fragmenter_workers>

The number of fragmentation workers to spawn

Default: 1

--n-qc-compute-workers <n_qc_compute_workers>

The number of QC compute workers to spawn

Default: 1

--qc-compute-n-cores <qc_compute_n_cores>: The maximum number of cores ( / CPUs) to reserve per QC compute worker. The actual number of cores utilised will depend on the type of QC calculation being performed. If no value is specified, all CPUs will be made available to each worker.

--qc-compute-max-mem <qc_compute_max_mem>: The maximum memory in GB available to each core of each QC worker. If no value is specified, the full machine memory will be made available to each worker.

--n-optimizer-workers <n_optimizer_workers>

The number of optimizer workers to spawn

Default: 1

--launch-redis, --no-launch-redis

Whether to launch a redis server if an already running one cannot be found.

Default: True

list

List the ids of any bespoke optimizations.

openff-bespoke executor list [OPTIONS]

Options

--status <status_filter>

The (optional) status to filter by

Options: waiting | running | errored | success

retrieve

Retrieve the current output of a bespoke optimization.

openff-bespoke executor retrieve [OPTIONS]

Options

--id <optimization_id>: Required The id of the optimization to retrieve

--output <output_file_path>: The JSON file to save the results to

--force-field <force_field_path>: The path to save the force field to

run

Run bespoke optimization using a temporary executor.

If you are running many bespoke optimizations it is recommended that you first launch a bespoke executor using the launch command and then submit the optimizations to it using the submit command.

openff-bespoke executor run [OPTIONS]

Options

--file <input_file_path>: The file containing the molecule of interest

--smiles <molecule_smiles>: The SMILES string representation of the input molecule.

--workflow <workflow_name>

The name of the built-in bespoke fitting workflow to use.

Options: default | debug

--workflow-file <workflow_file_name>: The path to a serialized bespoke workflow factory that encodes the bespoke fitting workflow to use.

--output <output_file_path>

The path [.json] to save the full results to

Default: output.json

--output-force-field <output_force_field_path>: The (optional) path [.offxml] to save the bespoke force field to if the fit succeeded

--force-field <force_field_path>: A custom initial force field to start the bespoke fits from.

--target-torsion <target_torsion_smirks>: The SMIRKS pattern(s) that should be used to identify the bonds in the input molecule to generate bespoke torsions around if requested. It must only match the two atoms involved in the central bond. This argument can be specified multiple times if you wish to provide multiple patterns.

--default-qc-spec <default_qc_spec>: The program, method, and basis to use by default when performing any QC calculations, e.g. –default-qc-spec xtb gfn2xtb none. If no basis is required to be specified for a particular method (e.g. for ANI or XTB) then ‘none’ should be specified.

--directory <directory>: The directory to store any working and log files in. By default all files and logs will be stored in a temporary directory and deleted when the command exists.

--n-fragmenter-workers <n_fragmenter_workers>

The number of fragmentation workers to spawn

Default: 1

--n-qc-compute-workers <n_qc_compute_workers>

The number of QC compute workers to spawn

Default: 1

--qc-compute-n-cores <qc_compute_n_cores>: The maximum number of cores ( / CPUs) to reserve per QC compute worker. The actual number of cores utilised will depend on the type of QC calculation being performed. If no value is specified, all CPUs will be made available to each worker.

--qc-compute-max-mem <qc_compute_max_mem>: The maximum memory in GB available to each core of each QC worker. If no value is specified, the full machine memory will be made available to each worker.

--n-optimizer-workers <n_optimizer_workers>

The number of optimizer workers to spawn

Default: 1

--launch-redis, --no-launch-redis

Whether to launch a redis server if an already running one cannot be found.

Default: True

submit

Submit a new bespoke optimization to a running executor.

openff-bespoke executor submit [OPTIONS]

Options

--file <input_file_path>: The file containing the molecule of interest

--smiles <molecule_smiles>: The SMILES string representation of the input molecule.

--workflow <workflow_name>

The name of the built-in bespoke fitting workflow to use.

Options: default | debug

--workflow-file <workflow_file_name>: The path to a serialized bespoke workflow factory that encodes the bespoke fitting workflow to use.

--save-submission-info, --no-save-submission-info: If the submission table printed in the terminal, which maps input molecules to an optimization ID, should be saved to a csv file.

--force-field <force_field_path>: A custom initial force field to start the bespoke fits from.

--target-torsion <target_torsion_smirks>: The SMIRKS pattern(s) that should be used to identify the bonds in the input molecule to generate bespoke torsions around if requested. It must only match the two atoms involved in the central bond. This argument can be specified multiple times if you wish to provide multiple patterns.

--default-qc-spec <default_qc_spec>: The program, method, and basis to use by default when performing any QC calculations, e.g. –default-qc-spec xtb gfn2xtb none. If no basis is required to be specified for a particular method (e.g. for ANI or XTB) then ‘none’ should be specified.

watch

Watch the status of a bespoke optimization.

openff-bespoke executor watch [OPTIONS]

Options

--id <optimization_id>: Required The id of the optimization to watch

launch-worker

Launch a single worker of the requested type in the main process.

Used to connect workers to a remote bespokefit server.

Note:

By default bespokefit will automatically use all cores and memory made available to the worker which should be declared in the job submission script. To change these defaults see the settings BEFLOW_QC_COMPUTE_WORKER_N_CORES & BEFLOW_QC_COMPUTE_WORKER_MAX_MEM.

Args:

worker_type: The alias name of the worker type which should be started.

openff-bespoke launch-worker [OPTIONS]

Options

--worker-type <worker_type>

Required The type of bespokefit worker to launch

Options: fragmenter | qc-compute | optimizer

prepare

Prepare an optimizations’ input files based on its schema.

openff-bespoke prepare [OPTIONS]

Options

-i, --input <input_path>: The file path to a JSON serialized optimization stage schema.

-ff, --force-field <initial_force_field_path>: The file path to the starting force field.