MW data input file
===================

The data input file is used to provide particle positions, velocities, forces, dipoles, radius, electrode atoms charges and other specific information about the state of the system.

The file contains several sections which must be given in order. Each section starts with a title which gives the section name and some optional complementary information. The code reads automatically the given sections and skips them if not given. **The only mandatory sections are the *header*, *box* and *coordinates* sections**. Some sections are repeated for values at previous steps.

We strongly advise that user-built data files contain only coordinates (and velocities if needed for specific initialization). Otherwise, MW-generated restart files are to be used, to be sure that all the available information are in the correct format for one or several previous timesteps.

All data values, including the {step}, are given in atomic units. The different sections are

* [header](#header)
* [box](#box)
* [coordinates](#coordinates)
* [velocities](#velocities)
* [forces](#forces)
* [dipole](#dipoles)
* [radius](#radius)
* [charges](#charges)
* [potential_shift](#potential_shift)
* [piston_velocity](#piston_velocity)
* [thermostat](#thermostat)
* [barostat](#barostat)
* [polarization](#polarization)

This is the general skeleton:

```
# header
step                      {initial step number}
num_atoms                 {total number of atoms}
num_electrode_atoms       {total number of electrode atoms}
# box
{a} {b} {c}
# coordinates : {total number of atoms} atoms - step {step}
name(i) x(i,step) y(i,step) z(i,step)
(...) 1 line per atom
-> repeat {available steps for coordinates} times (including title)
# velocities : {total number of atoms} atoms - step {step}
name(i) vx(i,step) vy(i,step) vz(i,step)
(...) 1 line per atom
-> repeat {available steps for velocities} times (including title)
# forces : {total number of atoms} atoms - step {step}
name(i) fx(i,step) fy(i,step) fz(i,step)
(...) 1 line per atom
-> repeat {available steps for forces} times (including title)
# dipoles : {total number of atoms} atoms - step {step}
name(i) dx(i,step) dy(i,step) dz(i,step)
(...) 1 line per atom
-> repeat {available steps for dipoles} times (including title)
# radius : {total number of atoms} atoms - step {step}
name(i) delta(i,step) epsx(i,step) epsy(i,step) epsz(i,step)
(...) 1 line per atom
-> repeat {available steps for radii} times (including title)
# charges : {total number of electrode atoms} electrode_atoms - step {step}
name(i) q(i,step)
(...) 1 line per electrode atom
-> repeat {available steps for electrode charges} times (including title)
# potential_shift : step {step}
Chi potential_shift(step)
-> repeat {available steps for potential shift} times (including title)
# piston_velocity : step {step}
name(i) vz(i)
(...) 1 line per electrode type
# thermostat : {length of thermostat chain} links - step {step}
zeta(i,step) v_zeta(i,step) g_zeta(i,step)
(...) 1 line per link in the chain
-> repeat {available steps for thermostat chain} times (including title)
# barostat : {length of barostat chain} links - step {step}
zeta(i,step) v_zeta(i,step) g_zeta(i,step)
(...) 1 line per link in the chain
-> repeat {available steps for barostat} times (including title)
# polarization
p_ion_x p_ion_y p_ion_z
```

<a name="header">

# Header section

</a>

The format of the header section is given below: 

```
# header
step                      {initial step number}
num_atoms                 {total number of atoms}
num_electrode_atoms       {total number of electrode atoms}
```
where:
* *step* is the global step index
* *num_atoms* is the total number of atoms in the system (as defined in the *runtime.inpt* file)
* *num_electrode_atoms* is the number of electrode atoms (as defined in the *runtime.inpt* file)


<a name="box">

# Simulation box

</a>

The first data section defines the box side's length a, b, and c (in atomic units) in the *x*, *y*, and *z* direction, respectively. The box is always orthorhombic. In case of two-dimensional periodic boundary conditions, the box length in the *z* direction is taken into account for (i) the density profile limits and (ii) the discretization of Ewald sums, so that the value should be chosen large (i.e. around 200 bohr).

```
# box
a b c
```

<a name="coordinates">

# Coordinates

</a>

The *coordinates* data section gives the *x*, *y*, and *z* coordinates at a specified timestep for all atoms in bohr.

The data must be grouped by species type and must be given in the same order as specified in the *runtime.inpt* file.

**WARNING:** No verification of this ordering is done.

The `name` parameter is an identifier for the species. It is there only for the user and to be used by an external viewer program. MW does not use this variable, but it is mandatory for a correct reading of the section.

```
# coordinates : {total number of atoms} atoms - step {step}
name(i) x(i,step) y(i,step) z(i,step)
(...) 1 line per atom
```

<a name="velocities">

# Velocities

</a>

The *velocities* data section gives the *x*, *y*, and *z* components of the velocities at a specified timestep for all atoms.

The data must be grouped by species type and must be given in the same order as specified in the *runtime.inpt* file.

If the *velocities* section does not appear, the velocities will be created with a pseudo-random Gaussian distribution.

The `name` parameter is an identifier for the species. It is there only for the user and to be used by an external viewer program. MW does not use this variable, but it is mandatory for a correct reading of the section.

```
# velocities : {total number of atoms} atoms - step {step}
name(i) vx(i,step) vy(i,step) vz(i,step)
(...) 1 line per atom
```

<a name="forces">

# Forces

</a>

The *forces* data section gives the  *x*, *y*, and *z* components of the forces at a specified timestep for all atoms.

The data must be grouped by species type and must be given in the same order as specified in the *runtime.inpt* file.

If the *forces* section does not appear in the file, the forces will be computed before entering the MD loop.

The `name` parameter is an identifier for the species. It is there only for the user and to be used by an external viewer program. MW does not use this variable, but it is mandatory for a correct reading of the section.

```
# forces : {total number of atoms} atoms - step {step}
name(i) fx(i,step) fy(i,step) fz(i,step)
(...) 1 line per atom
```


<a name="dipoles">

# Dipoles 

</a>

The *dipoles* data section gives the *x*, *y*, and *z* components of the dipoles at a specified timestep for all atoms.

The data must be grouped by species type and must be given in the same order as specified in the *runtime.inpt* file.

If the *dipoles* section does not appear in the file, the dipoles will be computed before entering the MD loop.

The `name` parameter is an identifier for the species. It is there only for the user and to be used by an external viewer program. MW does not use this variable, but it is mandatory for a correct reading of the section.

```
# dipoles : {total number of atoms} atoms - step {step}
name(i) dx(i,step) dy(i,step) dz(i,step)
(...) 1 line per atom
```


<a name="radius">

# Radius

</a>

The *radius* data section gives the delta and  *x*, *y*, and *z* components of the radius parameters at a specified timestep for all atoms.

The data must be grouped by species type and must be given in the same order as specified in the *runtime.inpt* file.

If the *radius* section does not appear in the file, the radius parameters will be computed before entering the MD loop.

The `name` parameter is an identifier for the species. It is there only for the user and to be used by an external viewer program. MW does not use this variable, but it is mandatory for a correct reading of the section.

```
# radius : {total number of atoms} atoms - step {step}
name(i) delta(i,step) epsx(i,step) epsy(i,step) epsz(i,step)
(...) 1 line per atom
```


<a name="charges">

# Charges

</a>

The *charges* data section gives the charges at a specified timestep for all electrode atoms.

The data must be grouped by electrode species type and must be given in the same order as specified in the *runtime.inpt* file.

If the *charges* section does not appear in the file, the charges will be computed before entering the MD loop.

The `name` parameter is an identifier for the species. It is there only for the user and to be used by an external viewer program. MW does not use this variable, but it is mandatory for a correct reading of the section.

```
# charges : {total number of electrode atoms} electrode_atoms - step {step}
name(i) q(i,step)
(...) 1 line per electrode atom
```


<a name="potential_shift">

# Potential_shift

</a>

The *potential_shift* data section gives the potential_shift, $`\chi`$, at a specified timestep due to the enforcement of the electroneutrality constraint in constant-potential simulations.

If the *potential_shift* section does not appear in the file, the potential shift will be computed before entering the MD loop.

**WARNING:** if the constant-potential simulation is performed with MaZe, the potential shift is an additional dynamical variable of the system and its value at previous timesteps must be given as described in the [MaZe initialization procedure](maze-initialization).

```
# potential_shift : step {step}
Chi potential_shift(step)
```

<a name="piston_velocity">

# Piston_velocity

</a>

The *piston_velocity* data section gives the piston velocity in the *z* direction at a specified timestep for each electrode type. If there are no electrodes in the system, this section must not appear.

The `name` parameter is an identifier for the electrode. MW does not use this variable, but it is mandatory for a correct reading of the section.

```
# piston_velocity : step {step}
name(i) vz(i)
(...) 1 line per electrode type
```

<a name="thermostat">

# Thermostat

</a>

The *thermostat* data section gives the thermostat position, velocity and acceleration at a specified timestep for all thermostat links in the chain.

If the section does not appear in the file, the thermostat parameters are initialized with 0 values.

```
# thermostat : {thermostat_chain_length} links - step {step}
zeta(i,step) v_zeta(i,step) g_zeta(i,step)
(...) 1 line per link in the chain
```

<a name="barostat">

# Barostat

</a>

The *barostat* data section gives the barostat position, velocity and acceleration at a specified timestep for all barostat links in the chain.

If the section does not appear in the file, the barostat parameters are initialized with 0 values.

```
# barostat : {barostat_chain_length} links - step {step}
zeta(i,step) v_zeta(i,step) g_zeta(i,step)
(...) 1 line per link in the chain
```

<a name="polarization">

# Polarization

</a>

The *polarization* data section gives the contribution of the non-metallic atoms (not in the electrodes) to the global polarization of the box.

If the section does not appear in the file, the polarization is computed on the first step.

```
# polarization
p_ion_x p_ion_y p_ion_z
```
