API Reference

Build peptide capture constructs (PCCs) composed of D-amino acids.

The builder mutates a reference PCC to the desired sequence, generates AMBER parameters with acpype, and prepares a solvated and equilibrated structure for subsequent free-energy calculations.

__init__(pcc, base_dir, settings_json, *, nodes=1, cores=1, threads=1)

Setup the PCCBuilder directories.

Parameters:

Name Type Description Default
pcc str

single letter string of AAs, ordered from arm to bead on the PCC structure.

 required
base_dir Path

directory to store the calculations

 required
settings_json Path

directory of settings.JSON file

 required
nodes int

number of nodes. Defaults to 1.

 1
cores int

cores per node. Defaults to 1.

 1
threads int

threads per core. Defaults to 1.

 1

Raises:

Type Description
ValueError

Raises Value error if base_dir is not a directory.

create(*, check=True)

Build, parameterize, and minimize a PCC.

This wrapper orchestrates the full PCC preparation workflow by sequentially calling :meth:_create_pcc, :meth:_get_params, and :meth:_minimize_PCC. Each stage is skipped if a corresponding .done file is present.

Parameters:

Name Type Description Default
check bool

If True (default), pause after PCC creation and after parameter generation to allow manual inspection of the intermediate structures. Rerun the method to continue to the next stage. If False, proceed through all stages without interruption.

 True

Returns:

Type Description
None

None

Handle preparation of the small-molecule target.

The class loads user-provided settings, generates force-field parameters with acpype, minimizes the structure, and exports the files required for complex assembly with a PCC.

__init__(settings_json, *, nodes=1, cores=1, threads=1)

Initialize the target molecule from a settings file.

Parameters:

Name Type Description Default
settings_json Path

Path to a JSON file with target configuration and I/O paths.

 required
nodes int

number of nodes. Defaults to 1.

 1
cores int

cores per node. Defaults to 1.

 1
threads int

threads per core. Defaults to 1.

 1

create()

Prepare the target molecule for use in FE calculations.

This wrapper runs acpype to generate parameters, minimizes the structure, and exports the relevant files. Each step is skipped if a .done marker exists.

Returns:

Type Description
None

None

Compute PCC–target binding free energies via PBMetaD simulations.

The workflow constructs the peptide capture construct (PCC) and target, generates AMBER parameters with acpype, equilibrates the complex in solution, runs parallel-bias metadynamics (PBMetaD), and prepares the output for free-energy analysis.

__init__(pcc, target, base_dir, temp, box, *, nodes=1, cores=1, threads=1, **kwargs)

Setup the base, PCC, and complex directories, and locate the target molecule files.

Parameters:

Name Type Description Default
pcc PCCBuilder

PCC structure for FE calculations.

 required
target TargetMol

Target molecule for FE calculations.

 required
base_dir Path

directory to store the calculations

 required
temp float

Temperature of the simulations

 required
box float

Size of the simulation box

 required
nodes int

number of nodes. Defaults to 1.

 1
cores int

cores per node. Defaults to 1.

 1
threads int

threads per core. Defaults to 1.

 1

Raises:

Type Description
ValueError

Raises Value error if base_dir is not a directory.

run(n_steps=None)

Execute the full free-energy calculation workflow.

The routine builds the complex, equilibrates it, performs PBMetaD, and reweights the resulting trajectory. The number of PBMetaD steps can be overridden with n_steps.

Parameters:

Name Type Description Default
n_steps int

Override the number of PBMetaD simulation steps.

 None

Returns:

Type Description
tuple

None

update_mdp(mdp_in, mdp_out, n_steps=None)

Update MDP files with the target temperature and step count.

Parameters:

Name Type Description Default
mdp_in Path

Path to the input template.

 required
mdp_out Path

Path to the output file.

 required
n_steps int

Number of steps to set in the output. If None the value from the template is retained.

 None

Returns:

Type Description

None

postprocess(fecalc, **kwargs)

Analyse a completed FECalc run and compute binding free energy.

This is the primary user-facing function. It expects that the PBMetaD simulation has been reweighted (see :meth:FECalc._reweight) and uses the resulting COLVAR file to compute the binding free energy and dissociation constant. Internally, the following steps are performed:

  1. Read the COLVAR file with :func:_load_plumed.
  2. Discard the first discard_initial nanoseconds of data.
  3. Perform block analysis via :func:_block_anal_3d using n_folds blocks to estimate statistical uncertainty.
  4. Integrate the bound (dCOM < 2 nm) and unbound regions to obtain the free energy (:func:_calc_FE).
  5. Convert the free energy to a dissociation constant with :func:_calc_K.
  6. Write a metadata.JSON summary with :func:_write_report.

Parameters:

Name Type Description Default
fecalc FECalc

Completed :class:FECalc object.

 required
**kwargs

Optional arguments controlling the analysis. discard_initial (float): Time in nanoseconds to discard from the start of the trajectory. Defaults to 1 ns. n_folds (int): Number of blocks for block analysis. Defaults to 5.

 {}

Returns:

Type Description
None

None

postprocess_wrapper(PCC, target, ifdir, temperature, init_time, n_folds, box_size)

Command-line wrapper around :func:postprocess.

Parameters:

Name Type Description Default
PCC str

PCC identifier.

 required
target str

Target molecule name.

 required
ifdir str or Path

Input directory containing simulation output.

 required
temperature float

Simulation temperature in kelvin.

 required
init_time float

Initial time (ns) to discard.

 required
n_folds int

Number of blocks for block analysis.

 required
box_size float

Simulation box edge length (nm).

 required

Returns:

Type Description
None

None

cd

Context manager for changing the current working directory.

__enter__()

Change to the new working directory.

__exit__(etype, value, traceback)

Return to the original working directory.

__init__(newPath)

Store the new working directory.

extract_timestep(mdp_file)

Return the dt value from a GROMACS .mdp file.

Parameters

mdp_file : Path Path to the .mdp file to parse.

Returns

str The timestep specified by the dt field.

Raises

ValueError If the dt field is not present in the file.

run_gmx(cmd, **kwargs)

Run a gmx command with improved error reporting.

Parameters

cmd : list or str Command passed to :func:subprocess.run. If a string is provided it is executed with shell=True. **kwargs : dict Additional keyword arguments forwarded to subprocess.run.

Raises

RuntimeError If the command exits with a non-zero status. The raised error includes the command, stdout and stderr to aid debugging.

set_hw_env(scheduler, nodes, cores, threads)

Resolve hardware settings for various job schedulers.

Parameters

scheduler : str Name of the scheduler (e.g. "slurm", "pbs", "lsf", "local"). nodes : int Default number of nodes requested. cores : int Default number of cores per node. threads : int Default number of threads per core.

Returns

tuple[int, int, int] Resolved (nodes, cores, threads) based on environment variables for the given scheduler. The environment is not modified.