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_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.

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:

  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:

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:

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:
  • 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:

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]
    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:

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:

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:

A dictionary with keyword arguments for func.

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:

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:

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:

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.

See Also

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.

See Also

qmflows.cp2k_mm
An instance of CP2KMM.
job.block.settings
Parameter:

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:

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:

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:

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:

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:

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:

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.