# Monte Carlo Parameters

## Index

param

Description

param.type

The type of parameter mapping.

param.move_range

The parameter move range.

param.func

The callable for performing the Monte Carlo moves.

param.kwargs

A dictionary with keyword arguments for param.func.

param.validation.allow_non_existent

Whether to allow parameters, that are explicitly specified, for absent atoms.

param.validation.charge_tolerance

Check whether the net charge of the system is integer within a given tolerance.

param.validation.enforce_constraints

Whether to enforce the constraints for the initial user-specified parameters.

param.block.param

The name of the forcefield parameter.

param.block.unit

The unit in which the forcefield parameters are expressed.

param.block.constraints

A string or list of strings with parameter constraints.

param.block.guess

Estimate all non-specified forcefield parameters.

param.block.frozen

A sub-block with to-be frozen parameters.

psf

Description

psf.str_file

The path+filename to one or more stream file.

psf.rtf_file

The path+filename to one or more MATCH-produced rtf file.

psf.psf_file

The path+filename to one or more psf files.

psf.ligand_atoms

All atoms within a ligand.

pes

Description

pes.block.func

The callable for performing the Monte Carlo moves.

pes.block.ref

A list of reference values for when func operates on qmflows.Result objects.

pes.block.kwargs

A dictionary with keyword arguments for pes.block.func.

pes.block.err_func

A function for computing the auxilary error of the specified PES descriptor.

pes_validation

Description

pes_validation.block.func

The callable for performing the Monte Carlo validation.

pes_validation.block.ref

A list of reference values for when func operates on qmflows.Result objects.

pes_validation.block.kwargs

A dictionary with keyword arguments for pes_validation.block.func.

job

Description

job.type

The type of package manager.

job.molecule

One or more .xyz files with reference (QM) potential energy surfaces.

job.lattice

One or more CP2K .cell files with the lattice vectors of each mol in job.molecule.

job.block.type

An instance of a QMFlows Package.

job.block.settings

The job settings as used by job.block.type.

job.block.template

A settings template for updating job.block.settings.

monte_carlo

Description

monte_carlo.type

The type of Monte Carlo procedure.

monte_carlo.iter_len

The total number of ARMC iterations $$\kappa \omega$$.

monte_carlo.sub_iter_len

The length of each ARMC subiteration $$\omega$$.

monte_carlo.logfile

The name of the ARMC logfile.

monte_carlo.hdf5_file

The name of the ARMC .hdf5 file.

monte_carlo.path

The path to the ARMC working directory.

monte_carlo.folder

The name of the ARMC working directory.

monte_carlo.keep_files

Whether to keep all raw output files or not.

phi

Description

phi.type

The type of phi updater.

phi.gamma

The constant $$\gamma$$.

phi.a_target

The target acceptance rate $$\alpha_{t}$$.

phi.phi

The initial value of the variable $$\phi$$.

phi.func

The callable for updating phi.

phi.kwargs

A dictionary with keyword arguments for phi.func.

## param

All forcefield-parameter related options.

This settings block accepts an arbitrary number of sub-blocks.

Examples

param:
type: FOX.armc.ParamMapping
move_range:
start: 0.005
stop: 0.1
step: 0.005
ratio: null
func: numpy.multiply
kwargs: {}
validation:
allow_non_existent: False
charge_tolerance: 0.01
enforce_constraints: False

charge:
param: charge
constraints:
- '0.5 < Cd < 1.5'
- '-0.5 > Se > -1.5'
Cd: 0.9768
Se: -0.9768
O_1: -0.47041
frozen:
C_1: 0.4524
lennard_jones:
-   unit: kjmol
param: epsilon
Cd Cd: 0.3101
Se Se: 0.4266
Cd Se: 1.5225
frozen:
guess: uff
-   unit: nm
param: sigma
Cd Cd: 0.1234
Se Se: 0.4852
Cd Se: 0.2940
frozen:
guess: uff


param.type
Parameter

The type of parameter mapping.

Used for storing and moving user-specified forcefield values.

FOX.armc.ParamMapping

A ParamMappingABC subclass.

param.move_range
Parameter
• Type - array-like or dict

• Default Value - {"start": 0.005, "stop": 0.1, "step": 0.005, "ratio": None}

The parameter move range.

This value accepts one of the following two types of inputs:

1. A list of allowed moves (e.g. [0.9, 0.95, 1.05, 1.0]).

2. A dictionary with the "start", "stop" and "step" keys.

For example, the list in 1. can be reproduced with {"start": 0.05, "stop": 0.1, "step": 0.05, "ratio": None}.

When running the ARMC parallel procedure (monte_carlo.type = FOX.armc.ARMCPT) option 1. should be supplied as a nested list (e.g. [[0.9, 0.95, 1.05, 1.0], [0.8, 0.9, 1.1, 1.2]]) and option 2. requires the additional "ratio" keyword (e.g. [1, 2]).

param.func
Parameter
• Default Value - "numpy.multiply"

The callable for performing the Monte Carlo moves.

The passed callable should be able to take two NumPy arrays as a arguments and return a new one.

numpy.multiply()

Multiply arguments element-wise.

param.kwargs
Parameter
• Default Value - {}

A dictionary with keyword arguments for param.func.

param.validation.allow_non_existent
Parameter

Whether to allow parameters, that are explicitly specified, for absent atoms.

This check is performed once, before the start of the ARMC procedure.

param.validation.charge_tolerance
Parameter

Check whether the net charge of the system is integer within a given tolerance.

This check is performed once, before the start of the ARMC procedure. Setting this parameter to inf disables the check.

param.validation.enforce_constraints
Parameter

Whether to enforce the constraints for the initial user-specified parameters.

This option checks if the initially supplied parameters are compatible with all the supplied constraints; an error will be raised if this is not the case. Note that the constraints will always be enforced once the actual ARMC procedure starts.

param.block.param
Parameter

The name of the forcefield parameter.

Important

Note that this option has no default value; one must be provided by the user.

param.block.unit
Parameter

The unit in which the forcefield parameters are expressed.

See the CP2K manual for a comprehensive list of all available units.

param.block.constraints
Parameter

A string or list of strings with parameter constraints. Accepted types of constraints are minima/maxima (e.g. 2 > Cd > 0) and fixed parameter ratios (e.g. Cd == -1 * Se). The special $LIGAND alias can be used for representing all atoms within a single ligand. For example, $LIGAND is equivalent to 2 * O + C + H in the case of formate.

param.block.guess
Parameter

Estimate all non-specified forcefield parameters.

If specified, expects a dictionary with the "mode" key, e.g. {"mode": "uff"} or {"mode": "rdf"}.

param.block.frozen
Parameter

A sub-block with to-be frozen parameters.

Parameters specified herein will be treated as constants rather than variables. Accepts forcefield parameters (e.g. "Cd Cd" = 1.0) and, optionally, the guess key.

## psf

Settings related to the construction of protein structure files (.psf).

Note that the psf.str_file, psf.rtf_file and psf.psf_file options are all mutually exclusive; only one should be specified. Furthermore, this block is completelly optional.

Examples

psf:
rtf_file: ligand.rtf
ligand_atoms: [C, O, H]


psf.str_file
Parameter

The path+filename to one or more stream files.

Used for assigning atom types and charges to ligands.

psf.rtf_file
Parameter

The path+filename to one or more MATCH-produced rtf files.

Used for assigning atom types and charges to ligands.

psf.psf_file
Parameter

The path+filename to one or more psf files.

Used for assigning atom types and charges to ligands.

psf.ligand_atoms
Parameter

A list with all atoms within the organic ligands.

Used for defining residues.

## pes

Settings to the construction of potentialy energy surface (PES) descriptors.

This settings block accepts an arbitrary number of sub-blocks, each containg the func and, optionally, kwargs keys.

Examples

pes:
rdf:
func: FOX.MultiMolecule.init_rdf
kwargs:
atom_subset: [Cd, Se, O]
kwargs:
atom_subset: [Cd, Se]
energy:
func: FOX.properties.get_attr  # i.e. qmflows.Result(...).energy
ref: [-17.0429775897]
kwargs:
name: energy
hirshfeld_charges:
func: FOX.properties.call_method  # i.e. qmflows.Result(...).get_hirshfeld_charges()
ref:
- [-0.1116, 0.1930, -0.1680, -0.2606, 0.1702, 0.0598, 0.0575, 0.0598]
kwargs:
name: get_hirshfeld_charges


pes.block.func
Parameter

A callable for constructing a PES descriptor.

The callable should return an array-like object and, as sole positional argument, take either a FOX.MultiMolecule or qmflows.Results instance. In the latter case one must supply a list of reference PES-descriptor-values to pes.block.ref.

Important

Note that this option has no default value; one must be provided by the user.

FOX.MultiMolecule.init_rdf()

Initialize the calculation of radial distribution functions (RDFs).

FOX.MultiMolecule.init_adf()

Initialize the calculation of angular distribution functions (ADFs).

pes.block.ref
Parameter

A list of reference values for when func operates on qmflows.Result objects.

If not None, a list of array_like objects must be supplied here, one equal in length to the number of supplied molecules (see job.molecule).

pes.block.kwargs
Parameter
• Default Value - {}

A dictionary with keyword arguments for func.

pes.block.err_func
Parameter

A function for computing the auxilary error of the specified PES descriptor. The callable should be able to take two array-like objects as arguments and return a scalar.

FOX.armc.mse_normalized() & FOX.armc.mse_normalized_v2()

Return a normalized mean square error (MSE) over the flattened input.

FOX.armc.mse_normalized_weighted() & FOX.armc.mse_normalized_weighted_v2()

Return a normalized mean square error (MSE) over the flattened subarrays of the input.

FOX.armc.mse_normalized_max()

Return a maximum normalized mean square error (MSE) over the flattened subarrays of the input.

## pes_validation

Settings to the construction of potentialy energy surface (PES) validators.

Functions identically w.r.t. to the pes block, the exception being that PES descriptors calculated herein are do not affect the error; they are only calculated for the purpose of validation.

This settings block accepts an arbitrary number of sub-blocks, each containg the func and, optionally, kwargs keys.

Examples

pes_validation:
kwargs:
atom_subset: [Cd, Se]
mol_subset: !!python/object/apply:builtins.slice  # i.e. slice(None, None, 10)
- null
- null
- 10


pes_validation.block.func
Parameter

A callable for constructing a PES validators.

The callable should return an array-like object and, as sole positional argument, take either a FOX.MultiMolecule or qmflows.Results instance. In the latter case one must supply a list of reference PES-descriptor-values to pes_validation.block.ref.

The structure of this block is identintical to its counterpart in pes.block.func.

Important

Note that this option has no default value; one must be provided by the user.

FOX.MultiMolecule.init_rdf()

Initialize the calculation of radial distribution functions (RDFs).

FOX.MultiMolecule.init_adf()

Initialize the calculation of angular distribution functions (ADFs).

pes_validation.block.ref
Parameter

A list of reference values for when func operates on qmflows.Result objects.

If not None, a list of array_like objects must be supplied here, one equal in length to the number of supplied molecules (see job.molecule).

pes_validation.block.kwargs
Parameter
• Default Value - {}

A dictionary with keyword arguments for func.

The structure of this block is identintical to its counterpart in pes.block.kwargs.

## job

Settings related to the running of the various molecular mechanics jobs.

In addition to having two constant keys (type and molecule) this block accepts an arbitrary number of sub-blocks representing quantum and/or classical mechanical jobs. In the example above there are two of such sub-blocks: geometry_opt and md. The first step consists of a geometry optimization while the second one runs the actual molecular dynamics calculation. Note that these jobs are executed in the order as provided by the user-input.

Examples

job:
type: FOX.armc.PackageManager
molecule: .../mol.xyz

geometry_opt:
type: qmflows.cp2k_mm
settings:
prm: .../ligand.prm
cell_parameters: [50, 50, 50]
template: qmflows.templates.geometry.specific.cp2k_mm
md:
type: qmflows.cp2k_mm
settings:
prm: .../ligand.prm
cell_parameters: [50, 50, 50]
template: qmflows.templates.md.specific.cp2k_mm


job.type
Parameter

The type of Auto-FOX package manager.

Used for managing and running the actual jobs.

FOX.armc.PackageManager

A PackageManagerABC subclass.

job.molecule
Parameter

One or more .xyz files with reference (QM) potential energy surfaces.

Important

Note that this option has no default value; one must be provided by the user.

job.lattice
Parameter

One or more CP2K .cell files with the lattice vectors of each mol in job.molecule.

This option should be specified is one is performing calculations on periodic systems.

job.block.type
Parameter
• Type - str or qmflows.packages.Package instance

• Default Value - "qmflows.cp2k_mm"

An instance of a QMFlows Package.

qmflows.cp2k_mm

An instance of CP2KMM.

job.block.settings
Parameter
• Default Value - {}

The job settings as used by type.

In the case of PES-averaged ARMC one can supply a list of dictionaries, each one representing the settings for its counterpart in job.molecule.

If a template is specified then this block may or may not be redundant, depending on its completeness.

job.block.template
Parameter

A Settings template for updating settings.

The template can be provided either as a dictionary or, alternativelly, an import path pointing to a pre-existing dictionary. For example, "qmflows.templates.md.specific.cp2k_mm" is equivalent to import qmflows; template = qmflows.templates.md.specific.cp2k_mm.

qmflows.templates.md

Templates for molecular dynamics (MD) calculations.

qmflows.templates.geometry

Templates for geometry optimization calculations.

## monte_carlo

Settings related to the Monte Carlo procedure itself.

Examples

monte_carlo:
type: FOX.armc.ARMC
iter_len: 50000
sub_iter_len: 10
logfile: armc.log
hdf5_file: armc.hdf5
path: .
folder: MM_MD_workdir
keep_files: False


monte_carlo.type
Parameter

The type of Monte Carlo procedure.

FOX.armc.ARMC

The Addaptive Rate Monte Carlo class.

FOX.armc.ARMCPT

An ARMC subclass implementing a parallel tempering procedure.

monte_carlo.iter_len
Parameter

The total number of ARMC iterations $$\kappa \omega$$.

monte_carlo.sub_iter_len
Parameter

The length of each ARMC subiteration $$\omega$$.

monte_carlo.logfile
Parameter

The name of the ARMC logfile.

monte_carlo.hdf5_file
Parameter

The name of the ARMC .hdf5 file.

monte_carlo.path
Parameter

The path to the ARMC working directory.

monte_carlo.folder
Parameter

The name of the ARMC working directory.

monte_carlo.keep_files
Parameter

Whether to keep all raw output files or not.

## phi

Settings related to the ARMC $$\phi$$ parameter.

Examples

phi:
type: FOX.armc.PhiUpdater
gamma: 2.0
a_target: 0.25
phi: 1.0
kwargs: {}


phi.type
Parameter

The type of phi updater.

The phi updater is used for storing, keeping track of and updating $$\phi$$.

FOX.armc.PhiUpdater

A class for applying and updating $$\phi$$.

phi.gamma
Parameter
• Default Value - 2.0

The constant $$\gamma$$.

See (4). Note that a list must be supplied when running the ARMC parallel tempering procedure (monte_carlo.type = FOX.armc.ARMCPT)

phi.a_target
Parameter
• Default Value - 0.25

The target acceptance rate $$\alpha_{t}$$.

See (4). Note that a list must be supplied when running the ARMC parallel tempering procedure (monte_carlo.type = FOX.armc.ARMCPT)

phi.phi
Parameter
• Default Value - 1.0

The initial value of the variable phi.

See (3) and (4). Note that a list must be supplied when running the ARMC parallel tempering procedure (monte_carlo.type = FOX.armc.ARMCPT)

phi.func
Parameter
• Default Value - "numpy.add"

The callable for updating phi.

The passed callable should be able to take two floats as arguments and return a new float.

numpy.add()
A dictionary with further keyword arguments for phi.func.