### Table of Contents

- Program Overview
- On-line resources
- Core features
- Getting started
- Internal units and conventions
- Input files
- Input file tags
- Output files
- Output file tags
- Distributed execution
- A simple tutorial
- Frequently asked questions
- Troubleshooting
- Contributing
- Bibliography

### Search

# Output file tags¶

## List of available properties¶

The following list briefly describes all the property names that can be listed in the properties tag of the Input files, and which will be written in the output files.

**Eenvelope**:
The (gaussian) envelope function of the external applied electric field (values go from 0 to 1).

*dimension: atomic_unit;*

**Efield**:
The external applied electric field (x,y,z components in cartesian axes).

*dimension: atomic_unit; size: 3;*

**atom_f**:
The force (x,y,z) acting on a particle given its index. Takes arguments index and bead (both zero based). If bead is not specified, refers to the centroid.

*dimension: force; size: 3;*

**atom_f_path**:
The forces acting on all the beads of a particle given its index. Takes arguments index and bead (both zero based). If bead is not specified, refers to the centroid.

*dimension: length;*

**atom_p**:
The momentum (x,y,z) of a particle given its index. Takes arguments index and bead (both zero based). If bead is not specified, refers to the centroid.

*dimension: momentum; size: 3;*

**atom_v**:
The velocity (x,y,z) of a particle given its index. Takes arguments index and bead (both zero based). If bead is not specified, refers to the centroid.

*dimension: velocity; size: 3;*

**atom_x**:
The position (x,y,z) of a particle given its index. Takes arguments index and bead (both zero based). If bead is not specified, refers to the centroid.

*dimension: length; size: 3;*

**atom_x_path**:
The positions of all the beads of a particle given its index. Takes an argument index (zero based).

*dimension: length;*

**bead_potentials**:
The physical system potential energy of each bead.

*dimension: energy; size: nbeads;*

**bweights_component**:
The weight associated one part of the hamiltonian. Takes one mandatory argument index (zero-based) that indicates for which component of the hamiltonian the weight must be returned.

**cell_abcABC**:
The lengths of the cell vectors and the angles between them in degrees as a list of the form [a, b, c, A, B, C], where A is the angle between the sides of length b and c in degrees, and B and C are defined similarly. Since the output mixes different units, a, b and c can only be output in bohr.

*size: 6;*

**cell_h**:
The simulation cell as a matrix. Returns the 6 non-zero components in the form [xx, yy, zz, xy, xz, yz].

*dimension: length; size: 6;*

**chin_weight**:
The 3 numbers output are 1) the logarithm of the weighting factor -beta_P delta H, 2) the square of the logarithm, and 3) the weighting factor

*size: 3;*

**conserved**:
The value of the conserved energy quantity per bead.

*dimension: energy;*

**density**:
The mass density of the physical system.

*dimension: density;*

**dipole**:
The electric dipole of the system (x,y,z components in cartesian axes).

*dimension: electric-dipole; size: 3;*

**displacedpath**:
This is the estimator for the end-to-end distribution, that can be used to calculate the particle momentum distribution as described in in L. Lin, J. A. Morrone, R. Car and M. Parrinello, 105, 110602 (2010), Phys. Rev. Lett. Takes arguments ‘ux’, ‘uy’ and ‘uz’, which are the components of the path opening vector. Also takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the end-to-end distribution estimator for. If not specified, all atoms are used. Note that one atom is computed at a time, and that each path opening operation costs as much as a PIMD step. Returns the average over the selected atoms of the estimator of exp(-U(u)) for each frame.

**ensemble_bias**:
The bias applied to the current ensemble

*dimension: energy;*

**ensemble_lp**:
The log of the ensemble probability

**ensemble_pressure**:
The target pressure for the current ensemble

*dimension: pressure;*

**ensemble_temperature**:
The target temperature for the current ensemble

*dimension: temperature;*

**exchange_all_prob**:
Probability of the ring polymer exchange configuration where all atoms are connected. It is divided by 1/N, so the number is between 0 and N, while the asymptotic value at low temperatures is 1.

*size: 1;*

**exchange_distinct_prob**:
Probability of the distinguishable ring polymer configuration, where each atom has its own separate ring polymer. A number between 0 and 1, tends to 1 in high temperatures, which indicates that bosonic exchange is negligible

*size: 1;*

**fermionic_sign**:
Estimator for the fermionic sign, also used for reweighting fermionic observables. Decreases exponentially with beta and the number of particles, but if not too large, can be used to recover fermionic statistics from bosonic simulations, see doi:10.1063/5.0008720.

*size: 1;*

**forcemod**:
The modulus of the force. With the optional argument ‘bead’ will print the force associated with the specified bead.

*dimension: force;*

**hweights_component**:
The weight associated one part of the hamiltonian. Takes one mandatory argument index (zero-based) that indicates for which component of the hamiltonian the weight must be returned.

**isotope_scfep**:
Returns the (many) terms needed to compute the scaled-coordinates free energy perturbation scaled mass KE estimator (M. Ceriotti, T. Markland, J. Chem. Phys. 138, 014112 (2013)). Takes two arguments, ‘alpha’ and ‘atom’, which give the scaled mass parameter and the atom of interest respectively, and default to ‘1.0’ and ‘’. The ‘atom’ argument can either be the label of a particular kind of atom, or an index (zero based) of a specific atom. This property computes, for each atom in the selection, an estimator for the kinetic energy it would have had if it had the mass scaled by alpha. The 7 numbers output are the average over the selected atoms of the log of the weights <h>, the average of the squares <h**2>, the average of the un-weighted scaled-coordinates kinetic energies <T_CV> and of the squares <T_CV**2>, the log sum of the weights LW=ln(sum(e**(-h))), the sum of the re-weighted kinetic energies, stored as a log modulus and sign, LTW=ln(abs(sum(T_CV e**(-h)))) STW=sign(sum(T_CV e**(-h))). In practice, the best estimate of the estimator can be computed as [sum_i exp(LTW_i)*STW_i]/[sum_i exp(LW_i)]. The other terms can be used to compute diagnostics for the statistical accuracy of the re-weighting process. Note that evaluating this estimator costs as much as a PIMD step for each atom in the list. The elements that are output have different units, so the output can be only in atomic units.

*size: 7;*

**isotope_tdfep**:
Returns the (many) terms needed to compute the thermodynamic free energy perturbation scaled mass KE estimator (M. Ceriotti, T. Markland, J. Chem. Phys. 138, 014112 (2013)). Takes two arguments, ‘alpha’ and ‘atom’, which give the scaled mass parameter and the atom of interest respectively, and default to ‘1.0’ and ‘’. The ‘atom’ argument can either be the label of a particular kind of atom, or an index (zero based) of a specific atom. This property computes, for each atom in the selection, an estimator for the kinetic energy it would have had if it had the mass scaled by alpha. The 7 numbers output are the average over the selected atoms of the log of the weights <h>, the average of the squares <h**2>, the average of the un-weighted scaled-coordinates kinetic energies <T_CV> and of the squares <T_CV**2>, the log sum of the weights LW=ln(sum(e**(-h))), the sum of the re-weighted kinetic energies, stored as a log modulus and sign, LTW=ln(abs(sum(T_CV e**(-h)))) STW=sign(sum(T_CV e**(-h))). In practice, the best estimate of the estimator can be computed as [sum_i exp(LTW_i)*STW_i]/[sum_i exp(LW_i)]. The other terms can be used to compute diagnostics for the statistical accuracy of the re-weighting process. Evaluating this estimator is inexpensive, but typically the statistical accuracy is worse than with the scaled coordinates estimator. The elements that are output have different units, so the output can be only in atomic units.

*size: 7;*

**isotope_zetasc**:
Returns the (many) terms needed to directly compute the relative probablity of isotope substitution in two different systems/phases. Takes four arguments, ‘alpha’ , which gives the scaled mass parameter and default to ‘1.0’, and ‘atom’, which is the label or index of a type of atoms. The 3 numbers output are 1) the average over the excess potential energy for scaled coordinates <sc>, 2) the average of the squares of the excess potential energy <sc**2>, and 3) the average of the exponential of excess potential energy <exp(-beta*sc)>

*size: 3;*

**isotope_zetasc_4th**:
Returns the (many) terms needed to compute the scaled-coordinates fourth-order direct estimator. Takes two arguments, ‘alpha’ , which gives the scaled mass parameter and default to ‘1.0’, and ‘atom’, which is the label or index of a type of atoms. The 5 numbers output are 1) the average over the excess potential energy for an isotope atom substitution <sc>, 2) the average of the squares of the excess potential energy <sc**2>, and 3) the average of the exponential of excess potential energy <exp(-beta*sc)>, and 4-5) Suzuki-Chin and Takahashi-Imada 4th-order reweighing term

*size: 5;*

**isotope_zetatd**:
Returns the (many) terms needed to directly compute the relative probablity of isotope substitution in two different systems/phases. Takes two arguments, ‘alpha’ , which gives the scaled mass parameter and default to ‘1.0’, and ‘atom’, which is the label or index of a type of atoms. The 3 numbers output are 1) the average over the excess spring energy for an isotope atom substitution <spr>, 2) the average of the squares of the excess spring energy <spr**2>, and 3) the average of the exponential of excess spring energy <exp(-beta*spr)>

*size: 3;*

**isotope_zetatd_4th**:
Returns the (many) terms needed to compute the thermodynamic fourth-order direct estimator. Takes two arguments, ‘alpha’ , which gives the scaled mass parameter and default to ‘1.0’, and ‘atom’, which is the label or index of a type of atoms. The 5 numbers output are 1) the average over the excess spring energy for an isotope atom substitution <spr>, 2) the average of the squares of the excess spring energy <spr**2>, and 3) the average of the exponential of excess spring energy <exp(-beta*spr)>, and 4-5) Suzuki-Chin and Takahashi-Imada 4th-order reweighing term

*size: 5;*

**kinetic_cv**:
The centroid-virial quantum kinetic energy of the physical system. Takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the kinetic energy of. If not specified, all atoms are used.

*dimension: energy;*

**kinetic_ij**:
The centroid-virial off-diagonal quantum kinetic energy tensor of the physical system. This computes the cross terms between atoms i and atom j, whose average is <p_i*p_j/(2*sqrt(m_i*m_j))>. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz]. Takes arguments ‘i’ and ‘j’, which give the indices of the two desired atoms.

*dimension: energy; size: 6;*

**kinetic_md**:
The kinetic energy of the (extended) classical system. Takes optional arguments ‘atom’, ‘bead’ or ‘nm’. ‘atom’ can be either an atom label or an index (zero-based) to specify which species or individual atom to output the kinetic energy of. If not specified, all atoms are used and averaged. ‘bead’ or ‘nm’ specify whether the kinetic energy should be computed for a single bead or normal mode. If not specified, all atoms/beads/nm are used.

*dimension: energy;*

**kinetic_opsc**:
The centroid-virial quantum kinetic energy of the physical system. Takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the kinetic energy of. If not specified, all atoms are used.

*dimension: energy;*

**kinetic_prsc**:
The Suzuki-Chin primitive estimator of the quantum kinetic energy of the physical system

*dimension: energy;*

**kinetic_td**:
The primitive quantum kinetic energy of the physical system. Takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the kinetic energy of. If not specified, all atoms are used.

*dimension: energy;*

**kinetic_tdsc**:
The Suzuki-Chin centroid-virial thermodynamic estimator of the quantum kinetic energy of the physical system. Takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the kinetic energy of. If not specified, all atoms are used.

*dimension: energy;*

**kinetic_tens**:
The centroid-virial quantum kinetic energy tensor of the physical system. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz]. Takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the kinetic tensor components of. If not specified, all atoms are used.

*dimension: energy; size: 6;*

**kstress_cv**:
The quantum estimator for the kinetic stress tensor of the physical system. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz].

*dimension: pressure; size: 6;*

**kstress_md**:
The kinetic stress tensor of the (extended) classical system. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz].

*dimension: pressure; size: 6;*

**kstress_tdsc**:
The Suzuki-Chin thermodynamic estimator for pressure of the physical system.

*dimension: pressure;*

**pot_component**:
The contribution to the system potential from one of the force components. Takes one mandatory argument index (zero-based) that indicates which component of the potential must be returned. The optional argument ‘bead’ will print the potential associated with the specified bead (interpolated to the full ring polymer). If the potential is weighed, the weight will be applied.

*dimension: energy;*

**pot_component_raw**:
The contribution to the system potential from one of the force components. Takes one mandatory argument index (zero-based) that indicates which component of the potential must be returned. The optional argument ‘bead’ will print the potential associated with the specified bead, at the level of discretization of the given component. Potential weights will not be applied.

*dimension: energy;*

**potential**:
The physical system potential energy. With the optional argument ‘bead’ will print the potential associated with the specified bead.

*dimension: energy;*

**potential_opsc**:
The Suzuki-Chin operator estimator for the potential energy of the physical system.

*dimension: energy;*

**potential_tdsc**:
The Suzuki-chin thermodyanmic estimator for the potential energy of the physical system.

*dimension: energy;*

**pressure_cv**:
The quantum estimator for pressure of the physical system.

*dimension: pressure;*

**pressure_md**:
The pressure of the (extended) classical system.

*dimension: pressure;*

**pressure_tdsc**:
The Suzuki-Chin thermodynamic estimator for pressure of the physical system.

*dimension: pressure;*

**r_gyration**:
The average radius of gyration of the selected ring polymers. Takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the radius of gyration of. If not specified, all atoms are used and averaged.

*dimension: length;*

**sc_op_scaledcoords**:
Returns the estimators that are required to evaluate the scaled-coordinates estimators for total energy and heat capacity for a Suzuki-Chin high-order factorization, as described in Appendix B of J. Chem. Theory Comput. 2019, 15, 3237-3249 (2019). Returns eps_v and eps_v’, as defined in that paper. As the two estimators have a different dimensions, this can only be output in atomic units. Takes one argument, ‘fd_delta’, which gives the value of the finite difference parameter used - which defaults to -0.0001. If the value of ‘fd_delta’ is negative, then its magnitude will be reduced automatically by the code if the finite difference error becomes too large.

*size: 2;*

**sc_scaledcoords**:
Returns the estimators that are required to evaluate the scaled-coordinates estimators for total energy and heat capacity for a Suzuki-Chin fourth-order factorization, as described in T. M. Yamamoto, J. Chem. Phys., 104101, 123 (2005). Returns eps_v and eps_v’, as defined in that paper. As the two estimators have a different dimensions, this can only be output in atomic units. Takes one argument, ‘fd_delta’, which gives the value of the finite difference parameter used - which defaults to -0.0001. If the value of ‘fd_delta’ is negative, then its magnitude will be reduced automatically by the code if the finite difference error becomes too large.

*size: 2;*

**scaledcoords**:
Returns the estimators that are required to evaluate the scaled-coordinates estimators for total energy and heat capacity, as described in T. M. Yamamoto, J. Chem. Phys., 104101, 123 (2005). Returns eps_v and eps_v’, as defined in that paper. As the two estimators have a different dimensions, this can only be output in atomic units. Takes one argument, ‘fd_delta’, which gives the value of the finite difference parameter used - which defaults to -0.0001. If the value of ‘fd_delta’ is negative, then its magnitude will be reduced automatically by the code if the finite difference error becomes too large.

*size: 2;*

**spring**:
The total spring potential energy between the beads of all the ring polymers in the system.

*dimension: energy;*

**step**:
The current simulation time step.

*dimension: number;*

**stress_cv**:
The total quantum estimator for the stress tensor of the physical system. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz].

*dimension: pressure; size: 6;*

**stress_md**:
The total stress tensor of the (extended) classical system. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz].

*dimension: pressure; size: 6;*

**temperature**:
The current temperature, as obtained from the MD kinetic energy of the (extended) ring polymer. Takes optional arguments ‘atom’, ‘bead’ or ‘nm’. ‘atom’ can be either an atom label or an index (zero-based) to specify which species or individual atom to output the temperature of. If not specified, all atoms are used and averaged. ‘bead’ or ‘nm’ specify whether the temperature should be computed for a single bead or normal mode.

*dimension: temperature;*

**ti_pot**:
The correction potential in Takahashi-Imada 4th-order PI expansion. Takes an argument ‘atom’, which can be either an atom label or index (zero based) to specify which species to find the correction term for. If not specified, all atoms are used.

*dimension: energy; size: 1;*

**ti_weight**:
The 3 numbers output are 1) the logarithm of the weighting factor -beta_P delta H, 2) the square of the logarithm, and 3) the weighting factor

*size: 3;*

**time**:
The elapsed simulation time.

*dimension: time;*

**vcom**:
The center of mass velocity (x,y,z) of the system or of a species. Takes arguments label (default to all species) and bead (zero based). If bead is not specified, refers to the centroid.

*dimension: velocity; size: 3;*

**vir_tdsc**:
The Suzuki-Chin thermodynamic estimator for pressure of the physical system.

*dimension: pressure;*

**virial_cv**:
The quantum estimator for the virial stress tensor of the physical system. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz].

*dimension: pressure; size: 6;*

**virial_fq**:
Returns the scalar product of force and positions. Useful to compensate for the harmonic component of a potential. Gets one argument ‘ref’ that should be a filename for a reference configuration, in the style of the FFDebye geometry input, and one that contains the input units.

*dimension: energy; size: 1;*

**virial_md**:
The virial tensor of the (extended) classical system. Returns the 6 independent components in the form [xx, yy, zz, xy, xz, yz].

*dimension: pressure; size: 6;*

**volume**:
The volume of the cell box.

*dimension: volume;*

## List of available trajectory files¶

The following list briefly describes all the trajectory types that can be listed in the trajectory tag of the Input files.

**Eforces**:
The external electric field contribution to the forces

*dimension: force;*

**becx**:
The x component of the Born Effective Charges in cartesian coordinates.

*dimension: number;*

**becy**:
The y component of the Born Effective Charges in cartesian coordinates.

*dimension: number;*

**becz**:
The z component of the Born Effective Charges in cartesian coordinates.

*dimension: number;*

**extras**:
The additional data returned by the client code. If the attribute “extra_type” is specified, and if the data is JSON formatted, it prints only the specified field. Otherwise (or if extra_type=”raw”) the full string is printed verbatim. Will print out one file per bead, unless the bead attribute is set by the user.

**extras_bias**:
The additional data returned by the bias forcefield, printed verbatim or expanded as a dictionary. See “extras”.

**extras_component_raw**:
The additional data returned by the client code, printed verbatim or expanded as a dictionary. See “extras”. Fetches the extras from a specific force component, indicated in parentheses and a specific bead [extras_component_raw(idx; bead=0)]. Never applies weighting or contraction, and does not automatically sum over beads as we don’t know if the extras are numeric

**f_centroid**:
The force acting on the centroid.

*dimension: force;*

**forces**:
The force trajectories. Will print out one file per bead, unless the bead attribute is set by the user.

*dimension: force;*

**forces_component**:
The contribution to the system forces from one of the force components. Takes one mandatory argument index (zero-based) that indicates which component of the potential must be returned. The optional argument ‘bead’ will print the potential associated with the specified bead (interpolated to the full ring polymer), otherwise the centoid force is computed. If the potential is weighed, the weight will be applied.

*dimension: force;*

**forces_component_raw**:
The contribution to the system forces from one of the force components. Takes one mandatory argument index (zero-based) that indicates which component of the potential must be returned. The optional argument ‘bead’ will print the potential associated with the specified bead (with the level of discretization of the component), otherwise the centoid force is computed. The weight of the potential is not applied.

*dimension: force;*

**forces_sc**:
The Suzuki-Chin component of force trajectories. Will print out one file per bead, unless the bead attribute is set by the user.

*dimension: force;*

**forces_spring**:
The spring force trajectories. Will print out one file per bead, unless the bead attribute is set by the user.

*dimension: force;*

**isotope_zetasc**:
Scaled-coordinates isotope fractionation direct estimator in the form of ratios of partition functions. Takes two arguments, ‘alpha’ , which gives the scaled mass parameter and default to ‘1.0’, and ‘atom’, which is the label or index of a type of atoms. All the atoms but the selected ones will have zero output

**isotope_zetatd**:
Thermodynamic isotope fractionation direct estimator in the form of ratios of partition functions. Takes two arguments, ‘alpha’ , which gives the scaled mass parameter and default to ‘1.0’, and ‘atom’, which is the label or index of a type of atoms. All the atoms but the selected ones will have zero output

**kinetic_cv**:
The centroid virial quantum kinetic energy estimator for each atom, resolved into Cartesian components [xx, yy, zz]

*dimension: energy;*

**kinetic_od**:
The off diagonal elements of the centroid virial quantum kinetic energy tensor [xy, xz, yz]

*dimension: energy;*

**momenta**:
The momentum trajectories. Will print out one file per bead, unless the bead attribute is set by the user.

*dimension: momentum;*

**p_centroid**:
The centroid momentum.

*dimension: momentum;*

**positions**:
The atomic coordinate trajectories. Will print out one file per bead, unless the bead attribute is set by the user.

*dimension: length;*

**r_gyration**:
The radius of gyration of the ring polymer, for each atom and resolved into Cartesian components [xx, yy, zz]

*dimension: length;*

**v_centroid**:
The centroid velocity.

*dimension: velocity;*

**v_centroid_even**:
The suzuki-chin centroid velocity.

*dimension: velocity;*

**v_centroid_odd**:
The suzuki-chin centroid velocity.

*dimension: velocity;*

**velocities**:
The velocity trajectories. Will print out one file per bead, unless the bead attribute is set by the user.

*dimension: velocity;*

**x_centroid**:
The centroid coordinates.

*dimension: length;*

**x_centroid_even**:
The suzuki-chin centroid coordinates.

*dimension: length;*

**x_centroid_odd**:
The suzuki-chin centroid coordinates.

*dimension: length;*