Chemical potential

This module calculates the excess chemical potential(s) for the current particle configuration. It uses Widom’s insertion method by randomly placing \(N_s\) test particles of species \(s\) uniformly within the simulation box. Then the potential energies \(U_i\) are computed for each particle from its interaction with the real particles. The excess chemical potential of species \(s\) is calculated as

\[\mu_\mathrm{ex}^{(s)} = -k_B T \log \left( \frac{1}{N} \sum_{i=1}^{N_s} \exp(-U_i/k_B T) \right).\]

The interactions that contribute to \(U_i\) must be defined explicitly, they should reproduce the interactions of the real system (i.e., the pair potentials). For an example, see examples/liquid/lennard_jones.lua.

class halmd.observables.chemical_potential(args)

Construct chemical potential module.

Parameters:

  • args (table) – keyword arguments

  • args.box – instance of halmd.mdsim.box

  • args.particle – instance of halmd.mdsim.particle

  • args.temperature (number) – temperature \(k_B T\) of the statistical ensemble

  • args.test_particles (table) – number of test particles per species

  • args.position (string) – name of position module

The argument test_particles is a table giving the number of test particles per species, starting with species #0.

The argument particle is an examplary particle of the simulation universe (in most cases there is only one such instance). It is used to deduce the space dimension, the maximal number of species’, and the compute device (memory) for the construction of the test particles.

The argument position is one of lattice and random and specifies a module in halmd.mdsim.positions to place the test particles. The default is random.

temperature

Temperature \(k_B T\) used to calculate the chemical potential. Assignment changes the internal value.

test_particle

The internal instance of halmd.mdsim.particle that contains the test particles.

add_force(args)

Define a new force on the test particles.

Parameters:

The function constructs a new force module of the type given by the first argument of the argument table (args[1]), which is then connected to the (internal) test particle instance.

The argument particle contains the real particles, which exert forces on the test particles.

The remaining arguments are passed to the force module. Use the box module specified upon construction of the chemical_potential module.

writer(args)

Write state variables to a file.

Parameters:

  • args (table) – keyword arguments

  • args.file – instance of file writer

  • args.every (number) – sampling interval

  • args.location (table) – location within file (optional)

  • args.labels (table) – labels of particle species

Returns:

instance of group writer

The optional argument location specifies a path in a structured file format like H5MD given as a table of strings. It defaults to {"observables"}.

The optional argument labels specifies the labels of the particle species in the output file as a table. The length of the table must match the length of test_particles passed to the constructor of the chemical_potential module. The default is {"A", "B", …}.

disconnect()

Disconnect chemical potential writer from observables sampler.

sample(species)

Returns a callable that computes and returns the chemical potential of the given species.

Parameters:

species (number) – species index, starting from 0

Returns:

callable

The argument species must be smaller than chemical_potential.result_size.

set_position()

Re-assign the positions of the test particles.