File formats

Input file .cfg

Specification

@params
[params]

@nuclei
[x y z charge]

@electrons
[x y z spin r]

@nuc_velocities
[# vx vy vz]

@elec_velocities
[# vx vy vz vr]

@nuc_masses
[# mx my mz]

@elec_masses
[# mx my mz mr]

@restraints
coordinate # [x y z]
distance # # [d]
angle # # # [ang]
dihedral # # # # [ang]
line # # # (at least 3)
plane # # # # (at least 4)
tether # # (at least 2)

Description

The only required fields are @params and at least one particle present in either @nuclei or @electrons.

The @params section describes the type of calculation to execute and related parameters, while the @nuclei and @electrons sections list the coordinates of the nuclei and electrons, with positions and electron radii in units of bohr, charges in electron charges, and spin = 1 for spin up and -1 for spin down. In these sections, appending the character # to a nuclear position, or an electron position or size, will freeze that coordinate during minimization or dynamics runs.

The @nuc_velocities and @elec_velocities section make it possible to specify initial velocities for individual particles. Not all the particles have to be listed here - if a particle does not appear in this section, the initial velocity will be set to zero, or to a random velocity from a Maxwell-Boltzmann distribution if a start_temperature is given. The index count # starts at 1.

Velocity units are in bohr per atu, where 1 atu = 1.03275 fs. As an example, the kinetic energy of a carbon nucleus moving at 1 bohr/atu would be

$$E = \frac{1}{2} (12\ \mathrm{amu}) * (1\ \mathrm{bohr/atu})^{2} = 6\ \mathrm{hartree}$$

or 163 eV.

The @nuc_masses and @elec_masses sections allow the user to assign different masses to different coordinates. If no entry is made, the program defaults to stored nuclei masses based on atomic weights, and sets the electron mass to the value given by electron_mass, using $[mx my mz mr] = [m_{e}, m_{e}, m_{e}, 0.75 m_{e}]$. Note that the factor of $\frac{3}{4}$ present in the semiclasssical equation of motion for the radial electron coordinate must be explicitly included. Masses are in atomic mass units.

Constraints and restraints

Constraints are quantities that remain fixed during a simulation. As mentioned above, appending # to a nuclear coordinate in the @nuclei section, or an electron coordinate in the @electrons section, will freeze the coordinate during a minimization or dynamics run.

Restraints are conditions the program tries to satisfy during a simulation through use of appropriate restraining potentials. The condition may not be exactly met during the simulation, and may never be met if a large enough force pushes the system away from the restraint. The restraining potentials modify the internal forces and energies, but only the non-restrained energies and forces are returned back to the user.

Restraints can act between any collection of nuclei and electrons. When referencing particles, the prefix "e" is used to refer to an electron, e.g. 4 refers to nucleus 4, but e5 refers to electron 5.

The following restraint types are supported by eFF:

• coordinate # [x y z]. Units in bohr. Restrains the particle to the position (x, y, z) using a harmonic potential with $k_{\mathrm{coord}}$ = 0.1 hartree/ $\mathrm{bohr}^{2}$.
• distance # # [d]. Units in bohr. Restrains the distance between two particles to $d$ using a harmonic potential with $k_{\mathrm{distance}}$ = 1.0 hartree/ $\mathrm{bohr}^{2}$.
• angle # # # [angle]. Units in degrees. Restrains the angle between three particles to angle using a harmonic potential with $k_{\mathrm{angle}}$ = 100.0 hartree/ $\mathrm{radian}^{2}$.
• dihedral # # # # [angle]. Units in degrees. Restrains the dihedral between four particles to angle using a harmonic potential with $k_{\mathrm{dihedral}}$ = 100.0 hartree/ $\mathrm{radian}^{2}$.
• line # # # (at least 3). Restrains the particles to lie on a least-squares line, using a harmonic potential based on the orthogonal distance from each point to the line, with $k_{\mathrm{line}}$ = 1.0 hartree/ $\mathrm{bohr}^{2}$.
• plane # # # # (at least 4). Restrains the particles to lie on a least-squares plane, using a harmonic potential based on the orthogonal distance from each point to the plane, with $k_{\mathrm{plane}}$ = 1.0 hartree/ $\mathrm{bohr}^{2}$.
• tether # # (at least 2). Averages the forces (or mass-scaled forces, for dynamics) and initial velocities on the particles so that the relative distance between them remains fixed. Useful for frozen-core calculations, e.g. tether e1 1 prevents electron 1 from oscillating relative to nucleus 1.

Output file .eff

Each line in the output file starts with a tag that is enclosed in square brackets, e.g. [params]. This makes it simple to search for items in the output using commands such as grep. When the tag is followed by more than one number, a header tag is also included in the output which labels the different parameters. For example, the following line may appear:

  [position_nuc]  3     0.500000   1.000000   0.500000

To find out what these numbers mean, we look for the a line containing the header tag position_nuc_header:

  [position_nuc_header]  Z   x   y   z

If we apply the grep command to the output file, we can selectively list the lines that are related to the positions of the nuclei:

  % cat output.eff | grep position_nuc

    [position_nuc_header]  Z   x   y   z
    [position_nuc]  1    0.000000   0.000000   0.000000
    [position_nuc]  2    0.000000   0.500000   0.000000
    [position_nuc]  3    0.500000   1.000000   0.500000
    ...

and so on. The output file is divided into several sections, listed below.

Listing of parameters used

This section lists the values of all the parameters known to the program, including default parameters not explicitly specified by the user.

[params] param = value

Fixed quantities relating to the nuclei and electrons

This section lists the number of nuclei and electrons, the charge on the nuclei and their atomic label, and the spins of the electrons, all of which are assumed to remain fixed during the calculation.

[num_nuclei]
[num_electrons]
[nuc_header] index Z label
[nuc]
[elec_header] index spin
[elec]

For a single point calculation

Particle energies and forces (section 3.2.2) and positions (section 3.2.2) are printed if desired.

For a minimization calculation

The [Minimize_iter_header] tag is printed at the beginning, then the [Minimize_iter] tag is printed every print_every iterations with the number of iterations, number of function evaluations, function value in Hartrees, and gradient squared (in reduced units internal to the program).

[Minimize_iter_header], # iters, # func evals, f, grad2
[Minimize_iter]

Particle energies and forces (section 3.2.2), positions (section 3.2.2), and restraints (section 3.2.2) are then printed if desired.

For a dynamics calculation

The [dynamics_header] tag is printed at the beginning, then the [dynamics_iter] tag is printed every print_every iterations with the time, kinetic energy (Hartrees), potential energy (Hartrees), total energy (Hartrees), target temperature (Kelvin), measured temperature (Kelvin), pressure kinetic energy rigid component (GPa), pressure kinetic energy flexible component (GPa), pressure potential energy rigid component (GPa), and pressure potential energy flexible component (GPa).

[dynamics_header], t(fs), kinetic_e, potential_e, total_e,
target_temp, measured_temp,
p_ke_rigid, p_ke_flexible, p_pe_rigid, p_pe_flexible
[dynamics_iter]

Particle energies and forces (section 3.2.2), positions (section 3.2.2), velocities (section 3.2.2), and restraints (section 3.2.2) are then printed if desired. Also, if adaptive_step_size is true, the following message is printed whenever the step size is shrunk:

[adaptive_step_size] step size set to [time_step],
energy difference is [delta_e],
try [num_tries] of [max_num_tries].

At the end of the calculation

The dipole moment, total energy, pressure, and elapsed time are printed out at the end of the calculation:

[total_dipole] in Debye
[total_energy] in hartrees
[pressure_rigid] in GPa
[pressure_flexible] in GPa
[cpu_time_elapsed] in seconds
[total_time_elapsed] in seconds

Particle energies and forces

The output of this section is controlled by the parameter output_energy_forces.

[energy_force_nuc_header], #, E, fx, fy, fz
[energy_force_nuc]
[energy_force_elec_header], #, E, fx, fy, fz, fr
[energy_force_elec]

Particle positions

The output of this section is controlled by the parameter output_positions.

[position_nuc_header], #, x, y, z
[position_nuc]
[position_elec_header], #, x, y, z, r
[position_elec]

Particle velocities

The output of this section is controlled by the parameter output_velocity.

[velocity_nuc_header], #, vx, vy, vz
[velocity_nuc]
[velocity_elec_header], #, vx, vy, vz, vr
[velocity_elec]

Restraints

The output of this section is controlled by the parameter output_restraints.

[restraint_coordinate_header], idx, x0, y0, z0, value
[restraint_coordinate]
[restraint_distance_header], idx1, idx2, distance, value
[restraint_distance]
[restraint_angle_header], idx1, idx2, idx3, angle, value
[restraint_angle]
[restraint_dihedral_header], idx1, idx2, idx3, idx4, dihedral, value
[restraint_dihedral]
[restraint_line_header], idx, distance
[restraint_line]
[restraint_plane_header], idx, distance
[restraint_plane]
[restraint_tether_header], idx
[restraint_tether]

Restart file .cfg.restart

The restart file is identical in format to the input .cfg file. All parameters are printed out, both the ones specified explicitly by the user, and the ones taken from default settings. Nuclear and electron coordinates and velocities are taken from the last saved step of the calculation; steps are saved every print_every steps. User-specified masses and restraint settings do not change during the calculation, and their values should be identical to those read in from the input file.