====== Manual ====== .. _arguments: Command line arguments ====================== Syntax:: acemd [--platform ] [--ncpus | --ngpus | --device [,,...]] [--help] ``--platform`` - Valid values: ``CPU``, ``CUDA``, ``OpenCL`` - Default: ``CUDA`` Platform to use for a simulation. ``CUDA`` is for the GPUs from *NVIDIA*, while ``OpenCL`` is for the rest GPUs. ``--ncpus`` - Valid values: positive integer - Default: all available CPUs Number of CPUs to use for a simulation. This is only relevant for ``--platform CPU``. ``--ngpus`` - Valid values: positive integer - Default: 1 Number of GPUs to use for a simulation. This is only relevant for ``--platform CUDA`` or ``--platform OpenCL``. ``--device`` - Valid values: list of GPU indices - Default: none List of GPU device indices to use for a simulation. The indices are separated by comma, but without spaces. If ``--device`` is set, it overrides ``--ngpus``. Run ``nvidia-smi`` to get the available device indices. Example:: acemd --device 0,2 ``--precision`` - Valid values: single, mixed, double - Default: mixed Set the precision mode on GPU devices. ``--license`` - Valid values: none Print the ACEMD license. ``--help`` - Valid values: none Show help message. ```` - Valid values: filename of a YAML or JSON input file - Default: ``input.yaml`` Input file (see :ref:`input options `). .. _input-options: Input file options ================== Input files are written in YAML or JSON format. The keywords are case-insensitive, but their arguments may be case-sensitive (*e.g.* filenames). Here you can find a list of all the available options with their default values. All options are explained in more details below. For the External forces and NNP options, see :ref:`extforces-options` and :ref:`nnp-options` for more details. .. code-block:: yaml # ACEMD Configuration File Documentation # Here we show the default values used if the option is not specified #--- System Structure and Parameters --- structure: null # Path to structure file (.psf or .prmtop) parameters: null # Path to parameter file(s) (.prm or .str for CHARMM, .xml for OpenMM) #--- Initial Conditions --- coordinates: null # Path to coordinate file (.pdb, .coor) boxsize: null # Box dimensions/vectors in Angstroms or NAMD XSC file path velocities: 298.15 # Path to velocity file (.vel or .pdb) or # temperature for initial velocity assignment (K) restart: false # Restart from checkpoint if available #--- Non-bonded Interactions --- pme: true # Use Particle Mesh Ewald for electrostatics cutoff: 9.0 # Non-bonded cutoff distance (Angstroms) switching: true # Use switching function for non-bonded interactions switchdistance: 7.5 # Distance at which switching function starts (Angstroms) #--- Implicit Solvent --- implicitsolvent: false # Use implicit solvent igb: 2 # Implicit solvent model #--- Integration --- timestep: 4.0 # Integration timestep (fs) hmr: null # Override default HMR setting hydrogenmass: 4.032 # Hydrogen mass for HMR (amu) hbondconstr: null # Override default H-bond constraints setting rigidwater: null # Override default rigid water setting #--- Temperature Control --- thermostat: false # Enable Langevin thermostat thermostattemperature: 298.15 # Target temperature (K) thermostatdamping: 1.0 # Thermostat damping (1/ps) #--- Pressure Control --- barostat: false # Enable barostat barostatpressure: 1.0 # Target pressure (bar) barostatanisotropic: false # Allow anisotropic xyz box scaling barostatconstratio: false # Keep xy ratio constant barostatconstxy: false # Keep xy dimensions constant #--- External Forces --- extforces: null # List of restraint specifications fbrefcoor: null # Reference coordinates for fixed/moving restraints #--- PLUMED --- plumedfile: null # PLUMED input file #--- Output Control --- trajectoryfile: "output.xtc" # Output trajectory file name trajvelocityfile: null # Output velocity trajectory file name trajforcefile: null # Output force trajectory file name trajectoryperiod: 25000 # Steps between trajectory frames stepzero: false # Output frame at step 0. Mostly used for debugging #--- Simulation Length --- run: 0 # Simulation length (steps or time unit: fs/ps/ns/us) minimize: 0 # Number of minimization steps (0 = no minimization) #--- Neural Network Potentials --- nnp: null # Neural network potential configuration System Structure and Parameters ------------------------------- *AMBER* and *CHARMM* force fields are supported: - For *AMBER*, both parameters and system topology are specified with ``structure``. - For *CHARMM*, system topology is specified with ``structure`` and parameters are specified with ``parameters``. ``structure`` - Valid values: filename of a PSF or PRMTOP file - Default: none ``parameters`` - Valid values: path to a PRM file or a list of PRM files - Default: none Can be either *CHARMM* force field parameters or *OpenMM* force field parameters. Examples .. code-block:: yaml structure: "structure.psf" parameters: ["./par_all36m_prot.prm", "./par_water_ions.prm"] structure: "structure-prepared.pdb" parameters: ["amber14-all.xml", "amber14/tip3pfb.xml"] Initial conditions ------------------ ``coordinates`` - Valid values: filename of any coordinate file supported by MoleculeKit - Default: none Initial system coordinates. If this argument is not set and the ``structure`` file contains coordinates, those will be used instead. ``boxSize`` - Valid values: list of real numbers or filename - Default: none Starting periodic box vectors. All units should be in Ångstrom and degrees. If not set, the box vectors are read from the ``structure`` file if present. If a filename is given, the box vectors are read directly from that file (supported formats: *NAMD* XSC, PDB, INPCRD, DCD, XTC). If the file contains a trajectory with multiple frames, the box vectors are read from the last frame. If a list of 6 numbers is given, it is used as the orthogonal or triclinic box lengths and angles. If a list of 3 lists of 3 numbers is given, it is used as the orthogonal or triclinic box vectors. Note that if triclinic box vectors are passed, they must satisfy the conditions of a triclinic box. 1. a_y, a_z and b_z must be zero 2. a_x, b_y and c_z must be positive 3. a_x/2 >= |b_x| 4. a_x/2 >= |c_x| 5. b_y/2 >= |c_y| Examples .. code-block:: yaml boxSize: [10.0, 25.0, 30.0] # 10.0 x 25.0 x 30.0 Angstrom box with 90 degree angles boxSize: [10.0, 25.0, 30.0, 90, 90, 90] # same as above boxSize: [[7.15, 0.0, 0.0], [2.386, 6.74, 0.0], [-2.38, 3.37, 5.84]] # truncated octahedron boxSize: input.xsc # Read box vectors from file ``velocities`` - Valid values: filename of PDB file or *NAMD* BINCOOR file or positive real number - Default: 298.15 Initial system velocities. If a filename is given, the velocities are read from the file. If a number is given, the velocities are generated from a Maxwell-Boltzmann distribution with the given number used as temperature (K) ``restart`` - Valid values: ``true``, ``false`` - Default: ``false`` Enable the restart of simulation from ``restart.chk`` file. The restart overrides the initial system coordinates, velocities, and box size. Also, the states of thermostat and barostart are overridden, if they are used. Note that ``restart.chk`` is always written every ``trajectoryPeriod`` steps irrespective of this option. Note that ``restart.chk`` can only be used to restart on the same hardware (i.e. a GPU has be of the same model). Non-bonded Interactions ----------------------- ``PME`` - Valid values: ``true``, ``false`` - Default: ``true`` Enable the particle-mesh Ewald summation for electrostatic interactions. ``cutoff`` - Valid values: positive real number - Default: 9.0 - Units: Angstrom Cutoff distance for van der Waals interactions and real-space electrostatic interactions. ``switching`` - Valid values: ``true``, ``false`` - Default: ``true`` Enable a switching function for van der Waals interactions. ``switchDistance`` - Valid values: positive real number - Default: 7.5 - Units: Angstrom Cutoff of the switching function. Implicit Solvent ---------------- ``implicitSolvent`` - Valid values: ``true``, ``false`` - Default: ``false`` Enable the implicit solvent (GBSA-OBC). Valid only for *AMBER* force field. ``igb`` - Valid values: 1, 2, 5, 7, 8 - Default: 2 Implicit solvent model. For more details see the table here: http://docs.openmm.org/latest/userguide/application/02_running_sims.html#amber-implicit-solvent Integration ----------- ``timeStep`` - Valid values: positive real number - Default: 4.0 - Units: fs Time step of an integrator. Note that the constraints and hydrogen mass repartitioning is enabled automatically: - If ``timeStep`` > 0.5 fs, enable hydrogen bond constraints and make water molecules rigid. - If ``timeStep`` > 2.0 fs, enable all bond constraints and repartition hydrogen mass. ``hmr`` - Valid values: ``true``, ``false`` - Default: ``null`` Enable hydrogen mass repartitioning. By default, HMR is enabled if ``timeStep`` > 2.0 fs. ``hydrogenMass`` - Valid values: positive real number - Default: 4.032 - Units: amu Mass of a hydrogen atom for the mass repartitioning. ``hbondConstr`` - Valid values: ``true``, ``false`` - Default: ``null`` Enable H-bond constraints. By default, H-bond constraints are enabled if ``timeStep`` > 0.5 fs. ``rigidWater`` - Valid values: ``true``, ``false`` - Default: ``null`` Enable rigid water. By default, rigid water is enabled if ``timeStep`` > 0.5 fs. Temperature Control ------------------- ``thermostat`` - Valid values: ``true``, ``false`` - Default: ``false`` Enable Langevin thermostat. ``thermostatTemperature`` - Valid values: non-negative real number - Default: 298.15 - Units: Kelvin Target temperature for the thermostat ``thermostatDamping`` - Valid values: non-negative real number - Default: 0.1 - Units: ps^-1 Damping constant of the thermostat. Pressure Control ---------------- ``barostat`` - Valid values: ``true``, ``false`` - Default: ``false`` Enable Monte Carlo barostat. ``barostatPressure`` - Valid values: real number - Default: 1.0 - Units: bar Target pressure of the barostat. ``barostatAnisotropic`` - Valid values: ``true``, ``false`` - Default: ``false`` Enable the axes (x, y, z) of the simulation box to vary independently. ``barostatConstRatio`` - Valid values: ``true``, ``false`` - Default: ``false`` Enable a constraint of x / y, while z varies independently. ``barostatConstXY`` - Valid values: ``true``, ``false`` - Default: ``false`` Enable a constraint of x and y, while z varies independently. .. _extforces-options: External Forces --------------- ACEMD supports a variety of external forces applying to the system. Forces are specified in the yaml file as a list under the ``extforces`` keyword. Positional restraints ^^^^^^^^^^^^^^^^^^^^^ Each positional restraint can be specified with the following options: .. code-block:: yaml extforces: - type: positionalRestraint # Type of restraint (required) sel: null # Atoms to which the force is applied (required) axes: "xyz" # Axes on which the force is applied fbWidth: [0, 0, 0] # Width of the flat-bottom potential in Å fbCenter: null # Center of the flat-bottom potential fbCenterOffset: [0, 0, 0] # Offset for the center of the flat-bottom potential setPoints: # List of force constant setpoints (required) - k@time # Force constant value at a given time ``sel`` - Valid values: atom selection in `VMD format `_ - Default: none Atom selection which defines the atoms on which to apply the restraining force. Take special care to not include hydrogens in the selection if using timestep larger than 2 fs, as the hydrogens are constrained to their corresponding heavy atoms and can cause NaN coordinates during the simulation. You can use the ``noh`` keyword to exclude hydrogens from a selection, see examples below. ``axes`` - Valid values: ``x``, ``y``, ``z``, ``+x``, ``-x``, ``+y``, ``-y``, ``+z``, ``-z`` or any string concatenation of them - Default: ``xyz`` Axes defines on which axes the restraint will be applied. By default it will be applied along all axes. If an axis has a ``+`` or ``-`` prefix, the restraint will be applied only to the specified direction of the axis leaving the other direction unrestrained. ``fbWidth`` - Valid values: list of 3 positive real numbers - Default: [0, 0, 0] Width of the flat-bottom potential. If just a single number is given, it is used for all defined ``axes``. By default the width is 0, which means that no flat-bottom potential is applied and the restraint applies directly a harmonic potential to the atom positions. If the width is not 0, each atom is restrained to its original position by a flat-bottom potential with the given width. If ``fbCenter`` is defined, the width is used to define the size of the single box within which all atoms of ``sel`` are restrained. ``fbCenter`` - Valid values: atomselection string or list of 3 real numbers - Default: none If an atomselection string is passed, it defines a single moving center for the flat-bottom potential. The **center of mass** of the selected atoms in ``fbCenter`` is used as the center of the flat-bottom potential. All atoms in ``sel`` are restrained inside a box centered at the moving center with the given ``fbWidth``. If a list of 3 real numbers is given, it defines a single fixed-position center for the flat-bottom potential. All atoms in ``sel`` are restrained inside a box centered at the given absolute xyz coordinates. ``fbCenterOffset`` - Valid values: list of 3 real numbers - Default: [0, 0, 0] Offset of the center of the flat-bottom potential from the center defined in ``fbCenter``. This can be useful for example to define a flat-bottom potential that is not centered directly on the center of mass of the selected atoms but 10 Å away from it in the z direction (e.g. ``fbCenterOffset: [0, 0, 10]``). ``setPoints`` - Valid values: list of ``k@time`` strings - Default: [] The setpoints define the force constant of the restraint (in kcal/mol/Ų) as a function of time. The force constant is linearly interpolated between the setpoints if there is more than one. If no setpoint is set for time 0, the restraint at time 0 will be 0 kcal/mol/Ų and will be interpolated to the specified next setpoint. If no setpoint is specified for the last step of the simulation, the last defined force constant will be used for the remaining simulation time. Time units can be specified as: - ``us``: microseconds - ``ns``: nanoseconds - ``ps``: picoseconds - ``fs``: femtoseconds - or as number of timesteps if no suffix is specified Example ^^^^^^^ .. code-block:: yaml extforces: # Keep the CA atoms restrained in place during the first 100ns with 1 kcal/mol/Ų - type: positionalRestraint sel: "protein and name CA" axes: "xyz" setpoints: - 1@0ns - 0@100ns # Restrain molecules named MOL within 10 Å of COM of the protein - type: positionalRestraint sel: "resname MOL" axes: "xyz" fbwidth: 10 fbcenter: "protein and name CA" setpoints: - 0.5@0 # Restrain molecules named MOL which are located above the membrane to stay within 20 Å # of the membrane by defining a box with a center +10 Å in the z direction from the # center of mass of the membrane and width 20 Å - type: positionalRestraint sel: "resname MOL and noh" axes: "z" fbwidth: 20 fbcenter: "(lipid or resname AR CHL DHA LAL MY OL PA PC PE PGR PGS PS SA SPM ST) and noh" fbcenteroffset: [0, 0, 10] setpoints: - 0.5@0 # Restrain the center of mass of the protein to [21, 13.5, -5] position - type: positionalRestraint sel: "protein and noh" axes: "xyz" fbwidth: 0 fbcenter: [21, 13.5, -5] setpoints: - 1@0 ``fbRefCoor`` - Valid values: filename of a PDB file - Default: none Reference coordinates for ``positionalRestraint`` restraints. The reference coordinates in ``fbRefCoor`` are used to calculate the reference atom positions to which the atoms are restrained. PLUMED ------ ``plumedFile`` - Valid values: filename of a *PLUMED* input file - Default: none Enables `PLUMED `_. It can be used to perform enhanced sampling simulations (i.e. metadynamics, steered MD, etc.) or apply complex restraints. For more details, see our :ref:`PLUMED tutorial ` and the *PLUMED* `documentation `_. Output Control -------------- The final atomic positions, velocities, and sizes of the simulation box are always written to ``output.coor``, ``output.vel`` and ``output.xsc``, respectively. ``trajectoryFile`` - Valid values: filename with a ``dcd`` or ``xtc`` extension - Default: ``output.xtc`` Name of a trajectory file for atomic positions. The trajectory is written in DCD or XTC format depending on the file extension. The positions are in Ångstrom. By default, the atomic positions are not wrapped. The atomic positions can be wrapped with `moleculekit `_. ``trajVelocityFile`` - Valid values: filename with a ``dcd`` extension - Default: none Name of a trajectory file for atomic velocities. The trajectory is written in DCD format only. The velocities are in arbitrary units, which can be converted to Å/ps by multiplying by 20.45482706 (`the standard of DCD `_). ``trajForceFile`` - Valid values: filename with a ``dcd`` extension - Default: none Name of a trajectory file for atomic forces. The trajectory is written in DCD format only. The forces are in kcal/mol/Å. ``trajectoryPeriod`` - Valid values: non-negative integer - Default: 25000 - Units: simulation steps Period of the trajectory files. Note that the log and restart files are written at the same period. ``stepZero`` - Valid values: ``true``, ``false`` - Default: ``false`` Write outputs for step 0 of the simulation. Mostly used for debugging to check on initial state and energies. Simulation Length ----------------- ``run`` - Valid values: non-negative integer - Default: 0 - Units: simulations steps or time units (see below) Lenght of simulations. The length can be specified in simulation steps or time using suffices (``us``, ``ns``, ``ps``, and ``fs``). ``minimize`` - Valid values: non-negative integer - Default: 0 - Units: steps Number of system minimization steps before starting a simulation. Note that the minimization is skipped if the simulation is restarted. Examples ^^^^^^^^ .. code-block:: yaml minimize: 500 run: 100ns .. _nnp-options: Neural Network Potentials ------------------------- .. code-block:: yaml nnp: file: null name: null sel: null type: null ``name`` - Valid values: string - Default: none Name of the NNP model. Currently supported models include TorchMD-Net and ANI variants. If it's set to ``ANI-2x``, ``ANI-1x``, or ``ANI-1ccx``, the NNP will use the corresponding ANI-2x, ANI-1x, or ANI-1ccx model. In that case you don't need to set ``file`` as it will be downloaded automatically. ``file`` - Valid values: filename of an NNP file - Default: none Path to a TorchMD-Net NNP file. ``sel`` - Valid values: atom selection in `VMD format `_ - Default: none Atom selection for the NNP. The atoms selected will be simulated with the NNP. All other atoms of the system will be simulated with the MM force field. ``type`` - Valid values: ``torch`` - Default: none Type of the NNP. Currently only ``torch`` model types are supported. Examples ^^^^^^^^ Example using TorchMD-Net: .. code-block:: yaml nnp: file: aceff_dft_v0.2.ckpt name: TorchMD-Net sel: "resname ACE ALA NME" type: torch Example using ANI-2x: .. code-block:: yaml nnp: name: ANI-2x sel: "resname ACE ALA NME" type: torch