### Install OpenFF BespokeFit with Mamba

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

This snippet provides the recommended commands to set up a new Conda environment and install `openff-bespokefit` along with its essential dependencies like `xtb-python` and `ambertools` using the `mamba` package manager. This ensures a functional environment for running BespokeFit.

```shell
mamba create -n bespokefit -y -c conda-forge mamba python=3.10
mamba activate bespokefit 
mamba install -y -c conda-forge openff-bespokefit xtb-python ambertools
```

--------------------------------

### Execute One-Off Bespoke Fit with `run` Command

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

Demonstrates how to perform a quick one-off bespoke fit for a single molecule using the `openff-bespoke executor run` command. It shows examples for providing input either as a SMILES string or a path to an SDF file, along with specifying the workflow, output files, and initial QC computation parameters.

```shell
openff-bespoke executor run --smiles             "CC(=O)NC1=CC=C(C=C1)O" \
                            --workflow           "default"               \
                            --output             "acetaminophen.json"    \
                            --output-force-field "acetaminophen.offxml"  \
                            --n-qc-compute-workers 2                     \
                            --qc-compute-n-cores   1                     \
                            --default-qc-spec xtb gfn2xtb none
```

```shell
openff-bespoke executor run --file               "acetaminophen.sdf"    \
                            --workflow           "default"              \
                            --output             "acetaminophen.json"   \
                            --output-force-field "acetaminophen.offxml" \
                            --n-qc-compute-workers 2                    \
                            --qc-compute-n-cores   1                    \
                            --default-qc-spec xtb gfn2xtb none
```

--------------------------------

### Execute Bespoke Optimization Workflow

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

A `BespokeOptimizationSchema` is fed into a `BespokeExecutor` to run the full workflow. The executor manages external program calls and parallelizes tasks across worker threads for efficient fitting. This example demonstrates submitting a workflow, waiting for completion, and saving the resulting force field or printing errors.

```python
from openff.bespokefit.executor import BespokeExecutor, BespokeWorkerConfig
from openff.bespokefit.executor.client import BespokeFitClient, Settings

# create a client to interface with the executor
settings = Settings()
client = BespokeFitClient(settings=settings)

with BespokeExecutor(
    n_fragmenter_workers = 1,
    n_optimizer_workers = 1,
    n_qc_compute_workers = 2,
    qc_compute_worker_config=BespokeWorkerConfig(n_cores=1)
) as executor:
    # Submit our workflow to the executor
    task_id = client.submit_optimization(input_schema=workflow_schema)
    # Wait until the executor is done
    output = client.wait_until_complete(task_id)

if output.status == "success":
    # Save the resulting force field to an OFFXML file
    output.bespoke_force_field.to_file("output-ff.offxml")
elif output.status == "errored":
    # OR the print the error message if unsuccessful
    print(output.error)
```

--------------------------------

### List BespokeFit Submissions

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

Prints a full list of all molecule submissions currently being processed by the BespokeFit executor. The list can be filtered by status, for example, to inspect only those submissions that have failed.

```shell
openff-bespoke executor list
```

```shell
openff-bespoke executor list --status errored
```

--------------------------------

### Install OpenEye Toolkits for Accelerated Operations

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs OpenEye Toolkits (`oechem`, `oequacpac`, `oeomega`) which can significantly speed up certain BespokeFit operations. Requires a free-for-academics license.

```shell
mamba install -c openeye openeye-toolkits
```

--------------------------------

### Initialize BespokeWorkflowFactory

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

The `BespokeWorkflowFactory` is central to the fitting pipeline, encoding all settings for the bespoke fitting process. It transforms an input molecule into a workflow describing how bespoke parameters will be generated. This example initializes the factory, specifying an initial force field and overriding the default QC specification to use GFN2-xTB.

```python
from openff.bespokefit.workflows import BespokeWorkflowFactory
from openff.qcsubmit.common_structures import QCSpec

factory = BespokeWorkflowFactory(
    # Define the starting force field that will be augmented with bespoke 
    # parameters.
    initial_force_field="openff-2.2.0.offxml",
    # Change the level of theory that the reference QC data is generated at
    default_qc_specs=[
        QCSpec(
            method="gfn2xtb",
            basis=None,
            program="xtb",
            spec_name="xtb",
            spec_description="gfn2xtb",
        )
    ]
)
```

--------------------------------

### Clone openff-bespokefit Repository from GitHub

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Clones the `openff-bespokefit` repository from GitHub to begin a source installation. Changes the current directory into the cloned repository.

```shell
git clone https://github.com/openforcefield/openff-bespokefit
cd openff-bespokefit
```

--------------------------------

### View OpenFF BespokeFit CLI Help

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

This command displays a comprehensive list of available commands and their respective help messages for the `openff-bespoke executor` command-line interface. It is useful for exploring the functionalities and options provided by the BespokeFit CLI.

```shell
openff-bespoke executor --help
```

--------------------------------

### Get CLI Help for openff-bespoke

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/bespoke-cli.md

Demonstrates how to access the help documentation for the `openff-bespoke` command line interface and its subcommands using the `--help` switch.

```sh
openff-bespoke --help
openff-bespoke executor launch --help
```

--------------------------------

### Install XTB-Python with MKL Backend for Performance

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs `xtb-python` configured to use MKL as its compute backend, potentially offering better performance on Intel CPUs. Note that MKL use may be subject to additional license agreements.

```shell
mamba install -c conda-forge xtb-python "libblas=*=*mkl"
```

--------------------------------

### Install openff-bespokefit Package from Source

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs the `openff-bespokefit` package into the currently active environment in editable mode (`-e .`), allowing for local development and modifications to be reflected without reinstallation.

```python
python -m pip install -e .
```

--------------------------------

### Install AmberTools Antechamber for Fragmentation

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs the free and open-source AmberTools package, specifically Antechamber, which is used as a fragmentation backend for molecules up to 40 heavy atoms.

```shell
mamba install -c conda-forge ambertools
```

--------------------------------

### Launch BespokeFit Executor

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

Launches the BespokeFit executor, configuring the number of workers dedicated to fragmentation, optimization, and QC computation stages. It is recommended to allocate most compute power to the QC compute stage due to its expense and parallelizability.

```shell
openff-bespoke executor launch --n-fragmenter-workers 1 \
                               --n-optimizer-workers  2 \
                               --n-qc-compute-workers 4 \
                               --qc-compute-n-cores   1
```

--------------------------------

### Set Initial Force Field for Parameter Optimization

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This example shows how to specify the initial force field file for parameter generation using the `initial_force_field` field. This force field serves as the starting point for the optimization process and should be in OFFXML format.

```python
factory.initial_force_field = "openff-2.2.0.offxml"
```

--------------------------------

### API Documentation for BespokeWorkflowFactory

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

This section provides a structured reference to the `BespokeWorkflowFactory` class, detailing its constructor parameters and key methods. It outlines the configurable options for customizing fitting workflows, including initial force fields, optimizers, and data specifications.

```APIDOC
BespokeWorkflowFactory:
  description: A factory for configuring and generating bespoke fitting workflows.
  constructor:
    parameters:
      - name: initial_force_field
        type: str
        description: The starting force field that will be augmented with bespoke parameters.
      - name: optimizer
        type: ForceBalanceSchema
        description: The underlying optimization engine schema.
      - name: parameter_hyperparameters
        type: List[ProperTorsionHyperparameters]
        description: Defines the types of bespoke parameters to generate and hyper-parameters that control how they will be fit.
      - name: target_templates
        type: List[TorsionProfileTargetSchema]
        description: The target reference data that should be used in the fit.
      - name: default_qc_specs
        type: List[QCSpec]
        description: The level of theory at which reference QC data is generated.
  methods:
    to_file(file_path: str):
      description: Saves the workflow factory configuration to a file (YAML or JSON).
      parameters:
        - name: file_path
          type: str
          description: The path to the file where the factory will be saved.
      returns: None
    from_file(file_path: str):
      description: Loads a workflow factory configuration from a file.
      parameters:
        - name: file_path
          type: str
          description: The path to the file from which the factory will be loaded.
      returns: BespokeWorkflowFactory
```

--------------------------------

### Load Bespoke Workflow Factory from File in Python

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

This snippet illustrates how to load a previously saved `BespokeWorkflowFactory` instance from a file. This simplifies the process of reusing and sharing configurations for reproducibility across different sessions or projects.

```python
factory = BespokeWorkflowFactory.from_file("workflow-factory.yaml")
```

--------------------------------

### Install TorchANI for Neural Network Potentials

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs TorchANI, a PyTorch implementation of ANI neural network potentials. This provides a much faster surrogate for generating QC reference data, suitable for neutral molecules with specific element coverage (C, H, N, O, S, F, Cl).

```shell
mamba install -c conda-forge torchani
```

--------------------------------

### Install openff-bespokefit with Mamba

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs the core `openff-bespokefit` package using the `mamba` package manager from the `conda-forge` channel. This is the recommended installation method.

```shell
mamba install -c conda-forge openff-bespokefit
```

--------------------------------

### Install XTB-Python for Semi-Empirical QC Data

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs the `xtb-python` package, providing access to XTB semi-empirical models. This can be used as a much faster surrogate when generating QC reference data.

```shell
mamba install -c conda-forge xtb-python
```

--------------------------------

### Set up BespokeFit Development Environment

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/CONTRIBUTING.md

Instructions for cloning the BespokeFit repository, creating and updating a Mamba environment with necessary dependencies, activating it, and installing the project in editable mode for development.

```shell
git clone https://github.com/openforcefield/openff-bespokefit.git
cd openff-bespokefit
mamba env create --file devtools/conda-envs/test-env.yaml --name bespokefit-dev
mamba env update --file devtools/conda-envs/docs-env.yaml --name bespokefit-dev
mamba activate bespokefit-dev
pip install -e .
```

--------------------------------

### Parallelize Bespoke Fit with Custom Worker Counts

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

Illustrates how to speed up the bespoke fitting process by specifying the number of workers for different stages of the workflow, such as fragmenter, optimizer, and QC computation, using the `openff-bespoke executor run` command.

```shell
openff-bespoke executor run --file                 "acetaminophen.sdf" \
                            --workflow             "default"           \
                            --n-fragmenter-workers 2                   \
                            --n-optimizer-workers  2                   \
                            --n-qc-compute-workers 2                   \
                            --qc-compute-n-cores   1                   \
                            --default-qc-spec xtb gfn2xtb none
```

--------------------------------

### Install Psi4 and DFTD3-Python for QC Data Generation

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Installs Psi4, an open-source quantum chemistry package, along with `dftd3-python`. This enables BespokeFit to generate bespoke quantum chemistry data and is recommended unless using a surrogate such as ANI.

```shell
mamba install -c conda-forge psi4 dftd3-python
```

--------------------------------

### Submit Molecule to BespokeFit Executor

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

Submits molecules to the BespokeFit executor for optimization. Molecules can be specified either using a SMILES pattern or by loading from an SDF (or similar) file. The command accepts multiple inputs and allows specifying the workflow and default QC specification.

```shell
openff-bespoke executor submit --smiles      "CC(=O)NC1=CC=C(C=C1)O" \
                               --workflow    "default"               \
                               --default-qc-spec xtb gfn2xtb none
```

```shell
openff-bespoke executor submit --file        "acetaminophen.sdf"   \
                               --workflow    "default"             \
                               --default-qc-spec xtb gfn2xtb none
```

--------------------------------

### Create BespokeFit Environment with AmberTools and Psi4

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Creates a new `conda` environment named `bespokefit-env` and installs `openff-bespokefit`, Psi4, `dftd3-python`, and AmberTools from `conda-forge`. This is an alternative for resolving potential incompatibilities when installing Psi4 into existing environments.

```shell
mamba create -n bespokefit-env -c conda-forge openff-bespokefit psi4 dftd3-python ambertools
```

--------------------------------

### Install Pre-commit Hooks for Code Quality

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/CONTRIBUTING.md

Instructions to install the 'pre-commit' tool via Mamba and then install the project's pre-commit hooks. These hooks automate code formatting and linting checks before each local commit, helping maintain code quality and avoid conflicts with remote automated checks.

```shell
mamba install pre-commit -c conda-forge
pre-commit install
```

--------------------------------

### Create and Activate Development Environment for Source Installation

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Creates a custom `conda` environment named `openff-bespokefit` using the `test-env.yaml` file from the `devtools/conda-envs` directory, which contains required dependencies. Activates the newly created environment.

```shell
mamba env create --name openff-bespokefit --file devtools/conda-envs/test-env.yaml
mamba activate openff-bespokefit
```

--------------------------------

### Configure Bespoke Workflow Factory in Python

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

This snippet demonstrates how to initialize and configure a `BespokeWorkflowFactory` instance. It shows how to set the initial force field, select an optimizer, define bespoke parameter hyperparameters, specify target templates, and configure default QC specifications for data generation.

```python
from openff.qcsubmit.common_structures import QCSpec

from openff.bespokefit.schema.optimizers import ForceBalanceSchema
from openff.bespokefit.schema.smirnoff import ProperTorsionHyperparameters
from openff.bespokefit.schema.targets import TorsionProfileTargetSchema

factory = BespokeWorkflowFactory(
    # Define the starting force field that will be augmented with bespoke 
    # parameters.
    initial_force_field="openff-2.2.0.offxml",
    # Select the underlying optimization engine.
    optimizer=ForceBalanceSchema(
        max_iterations=50, penalty_type="L1"
    ),
    # Define the types of bespoke parameter to generate and hyper-parameters 
    # that control how they will be fit, as well as the target reference data 
    # that should be used in the fit.
    parameter_hyperparameters=[ProperTorsionHyperparameters()],
    target_templates=[TorsionProfileTargetSchema()],
    # Change the level of theory that the reference QC data is generated at
    default_qc_specs=[
        QCSpec(
            method="gfn2xtb",
            basis=None,
            program="xtb",
            spec_name="xtb",
            spec_description="gfn2xtb",
        )
    ]
)
```

--------------------------------

### Monitor BespokeFit Procedure by ID

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

Monitors the progress of a specific bespoke fitting procedure using its unique molecule ID, which is provided by the executor upon submission.

```shell
openff-bespoke executor watch --id "1"
```

--------------------------------

### Create BespokeFit Environment with OpenEye Toolkits and Psi4

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/installation.md

Creates a new `conda` environment named `bespokefit-env` and installs `openff-bespokefit`, Psi4, `dftd3-python` from `conda-forge`, and OpenEye Toolkits from the `openeye` channel. This is an alternative for resolving potential incompatibilities when installing Psi4 into existing environments.

```shell
mamba create -n bespokefit-env -c conda-forge -c openeye openff-bespokefit psi4 dftd3-python openeye-toolkits
```

--------------------------------

### Save Bespoke Workflow Factory to File in Python

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

This snippet shows how to save a configured `BespokeWorkflowFactory` instance to a file, either in YAML or JSON format. This allows for easy recording and sharing of complex configurations, promoting reproducibility.

```python
factory.to_file("workflow-factory.yaml") # or .json
```

--------------------------------

### Launch Bespoke Executor for QC Cache

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

Starts the BespokeFit executor, specifying a working directory named 'bespoke'. This directory will be used to store the local QC cache data, speeding up parameterization.

```shell
openff-bespoke executor launch --directory bespoke
```

--------------------------------

### Retrieve Final BespokeFit Force Field

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

Retrieves the final optimized force field for a specific molecule using its unique ID. The output can be saved to a JSON file and an OFFXML file.

```shell
openff-bespoke executor retrieve --id          "1"                  \
                                 --output      "acetaminophen.json" \
                                 --force-field "acetaminophen.offxml"
```

--------------------------------

### Generate Optimization Schema from Molecule

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/quick-start.md

The `BespokeWorkflowFactory` can ingest any molecule represented by the OpenFF Toolkit's `Molecule` class. It then produces a `BespokeOptimizationSchema` which fully encodes the workflow for generating bespoke parameters for that specific molecule. This schema includes details on QC data generation, parameter types, hyperparameters, and the sequence of fitting steps.

```python
from openff.toolkit.topology import Molecule

input_molecule = Molecule.from_smiles("C(C(=O)O)N")  # Glycine

workflow_schema = factory.optimization_schema_from_molecule(
    molecule=input_molecule
)
```

--------------------------------

### Launch Bespoke Fragmentation Worker

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

Starts a specific type of BespokeFit worker, in this case, a fragmentation worker. This worker will connect to the executor specified by `BEFLOW_REDIS_ADDRESS` to process tasks.

```shell
openff-bespoke launch-worker --worker-type fragmenter
```

--------------------------------

### Get Machine IP Address

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

This command is used to display network interface configuration, including the IP address of the machine. It helps in identifying the address for connecting distributed components.

```shell
ifconfig -a
```

--------------------------------

### Launch Bespoke Executor Without Local Workers

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

Launches the BespokeFit executor, configured to not run any local fragmenter, optimizer, or QC compute workers. This setup is ideal when workers are distributed on different machines.

```shell
openff-bespoke executor launch --directory            "bespoke-executor" \
                               --n-fragmenter-workers 0                  \
                               --n-optimizer-workers  0                  \
                               --n-qc-compute-workers 0
```

--------------------------------

### Submit and Wait for BespokeFit Optimization in Python

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

This snippet shows how to use the `BespokeFitClient` within the `BespokeExecutor`'s context to submit an optimization task and wait for its completion. The executor starts upon entering the context and closes upon exiting, ensuring proper resource management. `wait_until_complete` blocks execution until the task finishes.

```python
from openff.bespokefit.executor.client import BespokeFitClient, Settings

client = BespokeFitClient(settings=Settings())

with executor:
    task_id = client.submit_optimization(input_schema=workflow)
    output = client.wait_until_complete(optimization_id=task_id)
```

--------------------------------

### openff-bespoke CLI API Reference

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/getting-started/bespoke-cli.md

Detailed API documentation for the `openff-bespoke` command line interface, generated from the `openff.bespokefit.cli:cli` entry point. This section outlines the full structure and available commands of the CLI.

```APIDOC
openff-bespoke CLI:
  Description: Main command-line interface for BespokeFit.
  Source Module: openff.bespokefit.cli
  Entry Point: cli
  Program Name: openff-bespoke
  Nested Commands: Enabled
  Commands:
    executor:
      Description: Manages BespokeFit executors.
      Subcommands:
        launch:
          Description: Launches an executor.
```

--------------------------------

### Build and View BespokeFit Documentation with Sphinx

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/CONTRIBUTING.md

Commands to build the project documentation using Sphinx and then open the generated HTML documentation in a web browser. This allows contributors to preview documentation changes locally.

```shell
sphinx-build -j auto docs docs/_build/html
firefox docs/_build/html/index.html
```

--------------------------------

### Initialize BespokeWorkflowFactory with Default Settings

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

Demonstrates how to construct a `BespokeWorkflowFactory` instance with its default settings. This factory can then be configured further by assigning values to its fields.

```python
from openff.bespokefit.workflows import BespokeWorkflowFactory

factory = BespokeWorkflowFactory()
```

--------------------------------

### ForceBalance Input File Template

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/openff/bespokefit/data/templates/force-balance/optimize.txt

A template for the ForceBalance input file, defining global options, convergence criteria, trust region parameters, and sections for dynamic extras and priors. This file is used to configure the ForceBalance optimization process.

```Configuration
# ForceBalance input file generated by MakeInputFile.py
# The octothorpe '#' is a comment symbol
# Note: If the specified value is 'None' then the option will truly be set to None - not the string 'None'
# Note: 'Section' option types are more complicated and may require you to read the documentation
# Note: Boolean option types require no value, the key being present implies 'True'

$options
# (string) Directory containing force fields, relative to project directory
ffdir forcefield

# (string) Type of the penalty, L2 or L1 in the optimizer
penalty_type {{ penalty_type }}

# (allcap) The job type, defaults to a single-point evaluation of objective function
jobtype {{ job_type }}

# (list) The names of force fields, corresponding to directory forcefields/file_name.(itp|gen)
forcefield force-field.offxml

# (int) Maximum number of steps in an optimization
maxstep {{ max_iterations }}

# (float) Convergence criterion of step size (just needs to fall below this threshold)
convergence_step {{ step_convergence_threshold }}

# (float) Convergence criterion of objective function (in MainOptimizer this is the stdev of x2 over 10 steps)
convergence_objective {{ objective_convergence_threshold }}

# (float) Convergence criterion of gradient norm
convergence_gradient {{ gradient_convergence_threshold }}

# The number of convergence criteria that must be met for main optimizer to converge
criteria {{ n_criteria }}

# (float) Minimum eigenvalue for applying steepest descent correction in the MainOptimizer
eig_lowerbound {{ eigenvalue_lower_bound }}

# (float) Step size for finite difference derivatives in many functions (get_(G/H) in fitsim, FDCheckG)
finite_difference_h {{ finite_difference_h }}

# (float) Factor for multiplicative penalty function in objective function
penalty_additive {{ penalty_additive }}

trust0 {{ initial_trust_radius }}
mintrust {{ minimum_trust_radius }}
error_tolerance {{ error_tolerance }}
adaptive_factor {{ adaptive_factor }}
adaptive_damping {{ adaptive_damping }}
normalize_weights {{ normalize_weights }}
# any extras are added here like print hessian
{%- for key, value in extras.items() %}
{{ key }}  {{ value if value is not none else "" }}
{%- endfor %}

# Charge constraints are taken care of using "evals".
constrain_charge false

priors
   {%- for key, value in priors.items() %}
   {{ key }} :  {{ value }}
   {%- endfor %}
/priors

$end

{{ targets_contents }}
```

--------------------------------

### Iterate and Define System-Specific Files for BespokeFit

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/openff/bespokefit/data/templates/force-balance/opt-geo-options.txt

This Jinja2 loop iterates through a list of 'systems' to define the name, geometry (.xyz), topology (.pdb), and mol2 (.sdf) files for each system. This is crucial for setting up individual molecular simulation inputs within the BespokeFit framework.

```Jinja2 BespokeFit Config
{%- for system in systems %}
$system
name {{ system }}
geometry {{ system }}.xyz
topology {{ system }}.pdb
mol2 {{ system }}.sdf
$end
{%- endfor %}
```

--------------------------------

### Launch Bespoke Executor with Default Workers via CLI

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

This command launches a dedicated bespoke executor using the `launch` command-line interface. By default, it creates a single worker for each stage (fragmenter, optimizer, QC compute), allowing each worker to access all available machine resources.

```shell
openff-bespoke executor launch --directory            "bespoke-executor" \
                               --n-fragmenter-workers 1                  \
                               --n-optimizer-workers  1                  \
                               --n-qc-compute-workers 1
```

--------------------------------

### OpenFF BespokeFit Ab Initio SMIRNOFF Fitting Configuration

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/openff/bespokefit/data/templates/force-balance/ab-initio-target.txt

This snippet represents a configuration file used by OpenFF BespokeFit to define an ab initio SMIRNOFF fitting job. It specifies the target name and weight, the type of fitting (AbInitio_SMIRNOFF), paths to input molecular files (mol2, pdb, coords), write level, and various energy and force fitting parameters. The template also includes a loop to dynamically add extra key-value pairs.

```Configuration Template
$target
name {{ name }}
weight {{ weight }}

type AbInitio_SMIRNOFF

mol2 input.sdf
pdb conf.pdb
coords scan.xyz

writelevel 1

attenuate {{ attenuate_weights | int }}

energy_denom {{ energy_denominator }}
energy_upper {{ energy_cutoff }}

energy {{ fit_energy | int }}
force {{ fit_force | int }}

{%- for key, value in extras.items() %}
{{ key }} {{ value if value is not none else "" }}
{%- endfor %}
$end
```

--------------------------------

### Load BespokeFit Workflow Factory from JSON File

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This snippet demonstrates how to load a previously saved BespokeFit workflow factory from a JSON file. The `BespokeWorkflowFactory.from_file()` class method reconstructs the factory instance, ensuring consistent workflow configuration.

```python
from openff.bespokefit.workflows import BespokeWorkflowFactory
factory = BespokeWorkflowFactory.from_file("my_bespoke_workflow.json")
```

--------------------------------

### Create BespokeFit Executor Instance in Python

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

This snippet demonstrates how to initialize a `BespokeExecutor` instance, configuring the number of workers and their compute resources for fragmentation, QC computation, and optimization tasks. It uses `BespokeWorkerConfig` to specify core allocation for each worker type.

```python
from openff.bespokefit.executor import BespokeExecutor, BespokeWorkerConfig

executor = BespokeExecutor(
    # Configure the workers that will fragment larger molecules
    n_fragmenter_workers=1,
    fragmenter_worker_config=BespokeWorkerConfig(n_cores=1),
    # Configure the workers that will generate any needed QC
    # reference data such as 1D torsion scans
    n_qc_compute_workers=1,
    qc_compute_worker_config=BespokeWorkerConfig(n_cores="auto"),
    # Configure the workers that will perform the final optimization
    # using the specified engine such as ForceBalance
    n_optimizer_workers=1,
    optimizer_worker_config=BespokeWorkerConfig(n_cores=1),
)
```

--------------------------------

### Specify Default QC Specifications for Reference Data Generation

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This code shows how to configure the generation of reference data using the `default_qc_specs` field. Instances of `QCSpec` define the program, method, basis set, and level of theory for QC calculations. The factory attempts specifications in order until a compatible one is found.

```python
from openff.qcsubmit.common_structures import QCSpec

factory.default_qc_specs = [QCSpec()]
```

--------------------------------

### Set Fragmentation Engine to WBOFragmenter

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

Illustrates how to configure the fragmentation scheme used by BespokeFit by assigning an instance of a `Fragmenter` subclass, such as `WBOFragmenter`, to the `fragmentation_engine` field. This ensures the Wiberg bond order of the target bond is preserved during fragmentation.

```python
from openff.fragmenter.fragment import WBOFragmenter

factory.fragmentation_engine = WBOFragmenter()
```

--------------------------------

### Update QC Cache from QCArchive Dataset

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

Updates the local QC cache by pulling data from a specified QCArchive dataset. The `--no-launch-redis` flag prevents launching a local Redis instance, and `--qcf-dataset` and `--qcf-address` define the source dataset and its API endpoint.

```shell
openff-bespoke cache update --no-launch-redis --qcf-dataset "OpenFF-benchmark-ligand-fragments-v2.0" --qcf-address "https://api.qcarchive.molssi.org:443/"
```

--------------------------------

### Launch Bespoke Executor with Resource-Limited QC Workers via CLI

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

This command launches a bespoke executor, demonstrating how to specify resource limits for workers to prevent over-subscription. It configures two QC compute workers, each allocated 8 CPU cores and 2.5 GB of memory per CPU, optimizing performance for parallel QC calculations. The memory limit is passed to the underlying QC engine.

```shell
openff-bespoke executor launch --directory            "bespoke-executor" \
                               --n-fragmenter-workers 1                  \
                               --n-optimizer-workers  1                  \
                               --n-qc-compute-workers 2                  \
                               --qc-compute-n-cores   8                  \
                               --qc-compute-max-mem   2.5
```

--------------------------------

### Configure Sphinx HTML Static Path for Templates

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/_templates/README.md

This Python snippet demonstrates how to configure Sphinx to include a `_templates` directory in its static file paths. Files within this directory will be copied to the build output, allowing them to override default Sphinx templates or provide custom static assets.

```Python
html_static_path = ['_templates']
```

--------------------------------

### Pydantic BaseModel API Reference

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/developers/schemas.md

This section provides an API reference for `pydantic.BaseModel`, which serves as the foundational class for all Pydantic models. It details key introspection methods inherited by BespokeFit models, facilitating object inspection and data manipulation in interactive environments.

```APIDOC
pydantic.BaseModel:
  Base class for Pydantic Models.
  Provides introspection methods and validation for fields.

  Methods:
    dict():
    copy():
    json():
    parse_file(filename: str):
      Read a json file with the given filename encoding an instance of a model.
    schema():
      Display the schema satisfied by instances of the model.
      This method is useful for inspecting the options available in a schema in an interactive environment.
```

--------------------------------

### BespokeFit Torsion Profile Calculation Configuration

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/openff/bespokefit/data/templates/force-balance/torsion-profile-target.txt

This snippet provides a template for configuring torsion profile calculations in OpenFF BespokeFit. It defines essential parameters such as the target name, weight, input molecular files (SDF, PDB, XYZ), energy thresholds, and output write levels. The configuration leverages Jinja2 templating to allow for dynamic insertion of values like `name`, `weight`, `attenuate_weights`, `energy_denominator`, `energy_cutoff`, and additional `extras`.

```Configuration Template
$target
name {{ name }}
weight {{ weight }}

type TorsionProfile_SMIRNOFF

mol2 input.sdf
pdb conf.pdb
coords scan.xyz

writelevel 2

attenuate {{ attenuate_weights | int }}

energy_denom {{ energy_denominator }}
energy_upper {{ energy_cutoff }}

{%- for key, value in extras.items() %}
{{ key }} {{ value if value is not none else "" }}
{%- endfor %}
$end
```

--------------------------------

### Jinja2 Template for OpenFF BespokeFit Target Configuration

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/openff/bespokefit/data/templates/force-balance/vibration-target.txt

This snippet provides a Jinja2 template used to generate target configuration files for OpenFF BespokeFit. It allows dynamic insertion of target properties like name, weight, and file paths, and includes conditional logic for optional parameters such as mode reassignment and extra key-value pairs.

```Jinja2
$target
name {{ name }}
weight {{ weight }}

type VIBRATION_SMIRNOFF

mol2 input.sdf
coords conf.pdb

writelevel 1

{%- if mode_reassignment is not none %}reassign {{ mode_reassignment }}{% endif %}

{%- for key, value in extras.items() %}
{{ key }} {{ value if value is not none else "" }}
{%- endfor %}
$end
```

--------------------------------

### Run BespokeFit Tests Locally with PyTest

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/CONTRIBUTING.md

Command to execute the project's unit and integration tests using PyTest. This should be run within the activated 'bespokefit-dev' Mamba environment to ensure all test dependencies are met.

```shell
pytest openff/bespokefit/_tests
```

--------------------------------

### Define OpenFF BespokeFit Optimization Geometry Target

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/openff/bespokefit/data/templates/force-balance/opt-geo-target.txt

This snippet presents a configuration template for an 'OptGeoTarget_SMIRNOFF' within the OpenFF BespokeFit system. It uses templating syntax to set the target's name, weight, and write level, and dynamically includes additional key-value pairs from an 'extras' dictionary.

```OpenFF BespokeFit Config
$target\nname {{ name }}\nweight {{ weight }}\n\ntype OptGeoTarget_SMIRNOFF\n\nwritelevel 1\n\n{%- for key, value in extras.items() %}\n{{ key }} {{ value if value is not none else "" }}\n{%- endfor %}\n$end
```

--------------------------------

### Retrieve Bespoke Fit Results via CLI

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-results.md

Retrieve the current status and output of a bespoke fit from the command line interface. The output, including the force field if the fit is successful, is saved to a specified JSON file.

```shell
openff-bespoke executor retrieve --id          "1"                \
                                 --output      "output.json"      \
                                 --force-field "bespoke-ff.offxml"
```

--------------------------------

### Configure BespokeFit Workflow Optimizer with ForceBalanceSchema

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This snippet demonstrates how to configure the optimizer for a BespokeFit workflow. It sets the `factory.optimizer` field to an instance of `ForceBalanceSchema`, which is used for optimizing torsion parameters with ForceBalance.

```python
from openff.bespokefit.schema.optimizers import ForceBalanceSchema

factory.optimizer = ForceBalanceSchema()
```

--------------------------------

### Load Bespoke Executor Output from JSON File

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-results.md

Load a `BespokeExecutorOutput` object from a previously saved JSON file. This is useful when the output was generated via the command line interface and needs to be processed in Python.

```python
from openff.bespokefit.executor import BespokeExecutorOutput
output = BespokeExecutorOutput.parse_file("output.json")
```

--------------------------------

### Construct BespokeFit Workflow from a Molecule

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This snippet demonstrates how to generate an optimization schema for a specific molecule using the configured workflow factory. It creates a `Molecule` object from a SMILES string and then calls `factory.optimization_schema_from_molecule()` to construct the workflow.

```python
from openff.toolkit import Molecule

biphenyl = Molecule.from_smiles("C1=CC=C(C=C1)C2=CC=CC=C2")
workflow = factory.optimization_schema_from_molecule(biphenyl)
```

--------------------------------

### Referencing OpenFF BespokeFit API Documentation

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/index.md

This reStructuredText directive configures the automatic generation of the API reference documentation for the `openff.bespokefit` Python package. It specifies that the documentation should be recursive, include an 'API Reference' caption, be placed under `ref/api`, and exclude signatures from the summary.

```reStructuredText
:::{\n}eval-rst\n.. autosummary::\n   :recursive:\n   :caption: \"API Reference\"\n   :toctree: ref/api\n   :nosignatures:\n\n   openff.bespokefit\n:::
```

--------------------------------

### Save BespokeFit Workflow Factory to JSON File

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This code shows how to persist a configured BespokeFit workflow factory to a JSON file. The `to_file()` method serializes the factory's configuration, enabling reproducibility and sharing.

```python
factory.to_file("my_bespoke_workflow.json")
```

--------------------------------

### Configure SMIRKS Settings for Bespoke Parameter Generation

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This snippet illustrates how to set up SMIRKS code generation for bespoke parameters using the `smirk_settings` field. An instance of `SMIRKSettings` allows control over options like expanding torsion terms and generating bespoke terms.

```python
from openff.bespokefit.utilities.smirks import SMIRKSettings

factory.smirk_settings = SMIRKSettings(
    expand_torsion_terms=True,
    generate_bespoke_terms=True,
)
```

--------------------------------

### Configure Torsion Parameter Selection with SMIRKS

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

Shows how to specify torsion parameters for bespoke fitting by assigning a list of SMIRKS patterns to the `target_torsion_smirks` field of the workflow factory. Each pattern should identify two indexed atoms to define the bond for torsion parameter generation.

```python
from openff.fragmenter.fragment import WBOFragmenter

factory.target_torsion_smirks = ['[!#1]~[!$(*#*)&!D1:1]-,=;!@[!$(*#*)&!D1:2]~[!#1]']
```

--------------------------------

### Combine Multiple Bespoke Force Fields via CLI

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-results.md

Create a single bespoke force field by combining multiple local force field files and task IDs from the command line interface. This is particularly useful for consolidating force fields from a congeneric series.

```shell
openff-bespoke combine --output "combined_forcefield.offxml"  \
                       --ff     "bespoke-ff.offxml"           \
                       --id     "2"                           \
                       --ff     "other-bespoke-ff.offxml"     \
                       --id     "3"
```

--------------------------------

### Jinja2 Template for Sphinx reStructuredText Module Documentation

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/_templates/autosummary/module.rst

This template generates a reStructuredText (.rst) file for a Python module, automatically listing its sub-modules, classes, functions, exceptions, and module-level attributes. It uses Sphinx's `automodule`, `currentmodule`, `autosummary`, and `autoattribute` directives to create structured API documentation based on introspection. The template dynamically filters items and handles full vs. relative paths for display.

```Jinja2
{{ objname | escape | underline(line="=")}}

.. automodule:: {{ fullname }}
   :no-members:

.. currentmodule:: {{ fullname }}

{% block modules %}
{% if modules %}
{{ _('Modules') | escape | underline(line="-") }}

.. autosummary::
   :toctree: {{objname}}
   :recursive:
{% for item in modules if item not in exclude_modules %}
   {% if item.startswith(fullname ~ ".") -%}
   {{- item[((fullname ~ ".") | length):] -}}
   {%- else -%}
   {{- item -}}
   {%- endif %}
{%- endfor %}
{% endif %}
{% endblock %}

{% block classes -%}

{%- set types = [] -%}
{%- for item in members -%}
   {%- if not item.startswith('_') and not (item in functions or item in attributes or item in exceptions) -%}
      {%- set _ = types.append(item) -%}
   {%- endif -%}
{%- endfor %}

{% if types %}
{{ _('Classes') | escape | underline(line="-") }}

   .. autosummary::
      :toctree: {{objname}}
      :nosignatures:
   {% for item in types %}
      {% if item.startswith(fullname ~ ".") -%}
      {{- item[((fullname ~ ".") | length):] -}}
      {%- else -%}
      {{- item -}}
      {%- endif %}
   {%- endfor %}

{% endif %}
{% endblock %}

{% block functions %}
{% if functions %}
{{ _('Functions') | escape | underline(line="-") }}

   .. autosummary::
      :toctree: {{objname}}
      :nosignatures:
   {% for item in functions %}
      {% if item.startswith(fullname ~ ".") -%}
      {{- item[((fullname ~ ".") | length):] -}}
      {%- else -%}
      {{- item -}}
      {%- endif %}
   {%- endfor %}

{% endif %}
{% endblock %}

{% block exceptions %}
{% if exceptions %}
{{ _('Exceptions') | escape | underline(line="-") }}

   .. autosummary::
      :toctree: {{objname}}
      :nosignatures:
   {% for item in exceptions %}
      {% if item.startswith(fullname ~ ".") -%}
      {{- item[((fullname ~ ".") | length):] -}}
      {%- else -%}
      {{- item -}}
      {%- endif %}
   {%- endfor %}

{% endif %}
{% endblock %}

{% block attributes %}
{% if attributes %}
{{ _('Module Attributes') | escape | underline(line="-") }}

   {% for item in attributes %}
   .. autoattribute:: {% if item.startswith(fullname ~ ".") -%}
                      {{- item[((fullname ~ ".") | length):] -}}
                      {%- else -%}
                      {{- item -}}
                      {%- endif %}
   {%- endfor %}

{% endif %}
{% endblock %}
```

--------------------------------

### Configure BespokeFit Executor via Environment Variables

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

This section documents the environment variables available for configuring the OpenFF BespokeFit Executor, affecting both CLI and Python API behavior. These variables provide fine-grained control over executor settings, such as temporary file management. The configuration is based on the `openff.bespokefit.executor.services.Settings` class.

```APIDOC
Class: openff.bespokefit.executor.services.Settings
  Description: Configuration settings for the Bespoke Executor, loadable from environment variables.
  Configurable Environment Variables:
    BEFLOW_KEEP_TMP_FILES: bool
      Description: Specifies whether temporary files generated during execution should be kept.
      Example Usage: Set to 'True' to retain temporary files for debugging or inspection.
```

```shell
$ BEFLOW_KEEP_TMP_FILES=True openff-bespoke executor ...
```

--------------------------------

### Setting Static Files Path in Sphinx conf.py

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/_static/README.md

This Python snippet demonstrates how to configure the `templates_path` variable within a Sphinx `conf.py` file. This setting specifies the directory where custom static files are located, allowing them to be copied to the build output and potentially overwrite default Sphinx static assets.

```Python
templates_path = ['_static']
```

--------------------------------

### Set Proper Torsion Hyperparameters for BespokeFit Workflow

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This code snippet shows how to specify hyperparameters for the BespokeFit workflow. It assigns a list containing `ProperTorsionHyperparameters` to the `factory.parameter_hyperparameters` field, focusing the optimization on proper torsion parameters.

```python
from openff.bespokefit.schema.smirnoff import  ProperTorsionHyperparameters

factory.parameter_hyperparameters = [ProperTorsionHyperparameters()]
```

--------------------------------

### Retrieve Bespoke Fit Results using Python API

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-results.md

Retrieve the current status and output of a bespoke fit using the Python API client. The output is returned as a `BespokeExecutorOutput` object, providing programmatic access to fit details.

```python
from openff.bespokefit.executor.client import BespokeFitClient, Settings

settings = Settings()
client = BespokeFitClient(settings=settings)

output = client.get_optimization(optimization_id="1")
```

--------------------------------

### Configure Target Schemas for QC Generation in BespokeFit

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-workflows.md

This snippet demonstrates how to specify target schemas using the `target_templates` field of a BespokeWorkflowFactory instance. Target schemas, such as `TorsionProfileTargetSchema`, define the types of reference data required for training bespoke parameters and how deviations contribute to the loss function.

```python
from openff.bespokefit.schema.targets import TorsionProfileTargetSchema

factory.target_templates = [TorsionProfileTargetSchema()]
```

--------------------------------

### Access BespokeExecutorOutput Attributes

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-results.md

Access various attributes of the `BespokeExecutorOutput` class to inspect the fit's progress and results. This includes checking the current status, any error messages, and retrieving the final bespoke force field.

```python
print(output.status)
print(output.error)
force_field = output.bespoke_force_field
```

--------------------------------

### Accessing Model Schemas Programmatically in Python

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/developers/schemas.md

This Python snippet demonstrates how to programmatically access the Pydantic schema of a BespokeFit model, specifically `BespokeWorkflowFactory`. The schema can be retrieved from both the class itself and an instance of the class, providing a detailed description of the model's configuration options.

```python
from openff.bespokefit.workflows.bespoke import BespokeWorkflowFactory

BespokeWorkflowFactory.schema()

factory = BespokeWorkflowFactory()
factory.schema()
```

--------------------------------

### Define Global Force Field Denominators in BespokeFit

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/openff/bespokefit/data/templates/force-balance/opt-geo-options.txt

This snippet sets global denominator values for bond, angle, dihedral, and improper terms within the OpenFF BespokeFit configuration. These values are typically used in force field parameterization to scale energy terms.

```BespokeFit Config
$global
bond_denom {{ bond_denominator }}
angle_denom {{ angle_denominator }}
dihedral_denom {{ dihedral_denominator }}
improper_denom {{ improper_denominator }}
$end
```

--------------------------------

### Set Bespoke Executor Address for Workers

Source: https://github.com/openforcefield/openff-bespokefit/blob/main/docs/users/bespoke-executor.md

Sets the `BEFLOW_REDIS_ADDRESS` environment variable, which specifies the IP address or hostname of the BespokeFit executor. This allows remote workers to connect to the central executor.

```shell
export BEFLOW_REDIS_ADDRESS="address"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.