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.block.weight`	A list of weights for the `err_func` output.

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:

Type - str or FOX.armc.ParamMappingABC subclass

Default Value - "FOX.armc.ParamMapping"

The type of parameter mapping.

Used for storing and moving user-specified forcefield values.

See Also

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:

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

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:

Type - str or Callable[[np.ndarray, np.ndarray], np.ndarray]

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.

See Also

numpy.multiply()
Multiply arguments element-wise.

param.kwargs¶

Parameter:

Type - dict[str, object]

Default Value - {}

A dictionary with keyword arguments for param.func.

param.validation.allow_non_existent¶

Parameter:

Type - bool

Default Value - False

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:

Type - float

Default Value - 0.01

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:

Type - bool

Default Value - False

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:

Type - str

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:

Type - str

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:

Type - str or list[str]

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:

Type - dict[str, str]

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:

Type - dict

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:

Type - str or list[str]

Default Value - None

The path+filename to one or more stream files.

Used for assigning atom types and charges to ligands.

psf.rtf_file¶

Parameter:

Type - str or list[str]

Default Value - None

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

Used for assigning atom types and charges to ligands.

psf.psf_file¶

Parameter:

Type - str or list[str]

Default Value - None

The path+filename to one or more psf files.

Used for assigning atom types and charges to ligands.

psf.ligand_atoms¶

Parameter:

Type - str or list[str]

Default Value - None

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]
    adf:
        func: FOX.MultiMolecule.init_adf
        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:

Type - str, Callable[[FOX.MultiMolecule], ArrayLike] or Callable[[qmflows.Result], ArrayLike]

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.

See Also

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:

Type - list[ArrayLike] or None

Default Value - None

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:

Type - dict[str, object]

Default Value - {}

A dictionary with keyword arguments for func.

pes.block.err_func¶

Parameter:

Type - str or Callable[[ArrayLike, ArrayLike], float]

Default Value - FOX.armc.default_error_func

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.

See Also

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.block.weight¶

Parameter:

Type - list[float]

Default Value - [1.0]

A list of positive weights for the err_func output. The list must contain exactly one entry for every molecule in job.molecule.

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:
    adf:
        func: FOX.MultiMolecule.init_adf
        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:

Type - str or Callable[[FOX.MultiMolecule], ArrayLike]

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.

See Also

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:

Type - list[ArrayLike] or None

Default Value - None

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:

Type - dict[str, object] or list[dict[str, object]]

Default Value - {}

A dictionary with keyword arguments for func.

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

Passing a list of dictionaries allows one the use different kwargs for different jobs in PES-averaged ARMC or ARMCPT:
job:
    molecule:
        - mol_CdSeO.xyz
        - mol_CdSeN.xyz

pes_validation:
    rdf:
        func: FOX.MultiMolecule.init_rdf
        kwargs:
            - atom_subset: [Cd, Se, O]
            - atom_subset: [Cd, Se, N]

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:

Type - str or FOX.armc.PackageManagerABC subclass

Default Value - "FOX.armc.PackageManager"

The type of Auto-FOX package manager.

Used for managing and running the actual jobs.

See Also

FOX.armc.PackageManager
A PackageManagerABC subclass.

job.molecule¶

Parameter:

Type - str or list[str]

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:

Type - str or list[str]

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.

See Also

qmflows.cp2k_mm
An instance of CP2KMM.

job.block.settings¶

Parameter:

Type - dict or list[dict]

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:

Type - dict or str

Default Value - {}

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.

See Also

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:

Type - str or FOX.armc.MonteCarloABC subclass

Default Value - "FOX.armc.ARMC"

The type of Monte Carlo procedure.

See Also

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:

Type - int

Default Value - 50000

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

monte_carlo.sub_iter_len¶

Parameter:

Type - int

Default Value - 100

The length of each ARMC subiteration $\omega$.

monte_carlo.logfile¶

Parameter:

Type - str

Default Value - "armc.log"

The name of the ARMC logfile.

monte_carlo.hdf5_file¶

Parameter:

Type - str

Default Value - "armc.hdf5"

The name of the ARMC .hdf5 file.

monte_carlo.path¶

Parameter:

Type - str

Default Value - "."

The path to the ARMC working directory.

monte_carlo.folder¶

Parameter:

Type - str

Default Value - "MM_MD_workdir"

The name of the ARMC working directory.

monte_carlo.keep_files¶

Parameter:

Type - bool

Default Value - "False"

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
    func: numpy.add
    kwargs: {}

phi.type¶

Parameter:

Type - str or FOX.armc.PhiUpdaterABC subclass

Default Value - "FOX.armc.PhiUpdater"

The type of phi updater.

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

See Also

FOX.armc.PhiUpdater
A class for applying and updating $\phi$.

phi.gamma¶

Parameter:

Type - float or list[float]

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:

Type - float or list[float]

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:

Type - float or list[float]

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:

Type - str or Callable[[float, float], float]

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.

See Also

numpy.add()
Add arguments element-wise.

phi.kwargs¶

Parameter:

Type - dict

Default Value - {}

A dictionary with further keyword arguments for phi.func.