# The ensemble keyword

## Purpose

• This keyword is used to set up an integration method (an integrator). The name of this keyword might be somewhat misleading, but is not very bad.

## Grammar

• The number of parameters depends on the first parameter, which can be:
```   nve
nvt_ber
nvt_nhc
nvt_bdp
nvt_lan
npt_ber
heat_nhc
heat_bdp
heat_lan
```
• When the first parameter is `nve`, it means that the ensemble for the current run is NVE (micro-canonical). There is no need to further specify any other parameters. Therefore, the full command is
```   ensemble nve
```
• When the first parameter is `nvt_ber`, it means that the ensemble for the current run is NVT (canonical) generated by using the Berendsen (ber) method [citation]. In this case, one needs to specify an initial target temperature `T_1`, a final target temperature `T_2`, and a parameter `T_coup` which reflects the strength of the coupling between the system and the thermostat. The full command is
```   ensemble nvt_ber T_1 T_2 T_coup
```

The target temperature (not the instant system temperature) will vary linearly from `T_1` to `T_2` during a run.

• When the first parameter is `nvt_nhc`, it is similar to the case of `nvt_ber`, but using the Nose-Hoover chain (nhc) method.
• When the first parameter is `nvt_bdp`, it is similar to the case of `nvt_ber`, but using the Bussi-Donadio-Parrinello (bdp) method.
• When the first parameter is `nvt_lan`, it is similar to the case of `nvt_ber`, but using the Langevin (lan) method.
• When the first parameter is `npt_ber`, it means that the ensemble for the current run is NPT (isothermal–isobaric) generated by using the Berendsen (ber) method [citation]. In this case, apart from the same parameters as in the case of `nvt_ber`, one needs to further specify the pressure components in three directions `Px`, `Py`, and `Pz`, and a pressure coupling constant `P_coup`. The full command is
```   ensemble npt_ber T_1 T_2 T_coup Px Py Pz P_coup
```
• When the first parameter is `heat_nhc`, it means heating a source region and simultaneously cooling a sink region using local Nose-Hoover chain thermostats. The full command is
```   ensemble heat_nhc T T_coup delta_T label_source label_sink
```

The target temperatures in the source region with label `label_source` and the sink region with label `label_sink` are `T+delta_T` and `T-delta_T`, respectively. Therefore, the temperature difference between the two regions is twice of `delta_T`. In the command above, the parameter `T_coup` has the same meaning as in the case of `nvt_nhc`.

• When the first parameter is `heat_bdp`, it is similar to the case of `heat_nhc`, but using the Bussi-Donadio-Parrinello (bdp) method.
• When the first parameter is `heat_lan`, it is similar to the case of `heat_nhc`, but using the Langevin (lan) method.
• About the units and parameter values.
• The units of temperature and pressure for this keyword are K and GPa, respectively.
• The temperature coupling constant in the Berendsen method can be any positive number less than or equal to 1 and we recommend a value in the range of [math][0.01, 1][/math]. A larger number results in a faster control of the temperature. The temperature coupling constant (the relaxation time) in the Nose-Hoover chain, BDP, and Langevin methods is in units of the time step and is recommended to be in the range of [math][10, 1000][/math]. Here, a larger number results in a slower control of the temperature.
• The pressure coupling constant in the Berendsen method should be a small positive number in the unit system adopted by `GPUMD`. We recommend a value in the range of [math][0.0001, 0.01][/math]. For a stiffer material (such as diamond or graphene), one should use a smaller value.
• In practice, all these parameters should be determined by try and error.

## Caveats

• One should use one and only one instance of this keyword for each run.

• None