Overview#

The libcasm-clexmonte package provides the CASM cluster expansion Monte Carlo implementations.

General approach#

At its most basic, Monte Carlo simulations are setup and performed using libcasm-clexmonte by following these steps:

  1. Construct a System.

  2. Construct a MonteCalculator.

  3. Construct an initial MonteCarloState.

  4. Construct a single SamplingFixtureParams, or a RunManager with multiple SamplingFixtureParams.

  5. Running Monte Carlo simulations.

An overview of the System, MonteCalculator, MonteCarloState, and SamplingFixtureParams classes and the methods used to run Monte Carlo simulations are given in the following sections.

System#

The System class holds data defining the crystal system and its properties, independent of a particular Monte Carlo method or particular state of the sytem. This includes:

The system data also includes other data such as local basis sets, local cluster expansions, and kinetic Monte Carlo events.

MonteCalculator#

The MonteCalculator class provides a standardized interface to Monte Carlo simulation implementations and to the data used during the simulation. This includes:

MonteCarloState#

The MonteCarloState data structure combines:

A MonteCarloState can be constructed by:

  • explicitly giving the exact configuration and conditions (using the MonteCarloState constructor), or

  • using the make_initial_state() or make_canonical_initial_state() methods to perform standard operations like finding the configuration with minimum potential, or fill a supercell with a certain shape or minimum volume with a motif configuration.

For canonical and kinetic Monte Carlo calculations, it may be useful to:

  • use the enforce_composition() method to perturb an MonteCarloState configuration to match a desired composition, or

  • set the conditions of the MonteCarloState to match its configuration.

SamplingFixtureParams#

A SamplingFixture is used to sample data, store results, and check for completion during a Monte Carlo simulation. SamplingFixtureParams is a data structure that specifies all the parameters that control a SamplingFixture. This includes:

  • sampling functions (StateSamplingFunction and jsonStateSamplingFunction), including both standard sampling functions provided by the implementation and user-provided custom sampling functions, which return the quantities (energy, composition, order parameters, etc.) sampled by the fixture,

  • sampling parameters (SamplingParams), specifying which sampling functions to evaluate and when the samples should be taken,

  • completion check parameters (CompletionCheckParams), which includes which sampled quantities should be converged, the requested absolute or relative precision level, how often to check, and minimum and maximum numbers of samples, steps or passes, computational or simulated time to run for,

  • results output parameters, including where to write output files, whether to only write a summary with mean values and estimated precisions, or to also write all observations, or the trajectory of configurations at each sample time, and

  • status logging parameters, including whether, where, and how often to write a status log file with the most recent completion check results.

RunManager#

In some cases it may be useful to use multiple sampling fixtures for a single Monte Carlo simulation. For instance, a sampling fixture for thermodynamic properties can be re-used and combined with a sampling fixture for kinetic properties during a kinetic Monte Carlo simulation, or sampling fixtures that sample different quantities at different intervals could be combined.

The RunManager class is used to hold one or more SamplingFixture and enables Monte Carlo methods to do sampling and convergence checking according to each sampling fixture. A global_cutoff parameter determines if all sampling fixtures must complete for the Monte Carlo run to finish, or if the run should stop when any one sampling fixture completes.

Additionally, the RunManager controls options for saving initial and final states of each run in order to enable re-starts of a series of runs and perform “dependent runs” where the final configuration of one run is used as the initial configuration of the next run at varying conditions.

Running Monte Carlo simulations#

Simulations can be run at single state using:

Main results, the average value of sampled quantities and estimated precision, and the calculation of quantities like the heat capacity and susceptibility from fluctuations of energy and composition, are stored in a results summary file. If additional runs are performed at different thermodynamic conditions, the values calculated from each subsequent run are stored by appending to lists in the results summary file. Often, for ease of thermodynamic integration to calculate free energies, runs are organized along linear paths in thermodynamic conditions space (for instance increasing temperature at constant chemical potential), with one summary file for one linear path.

Attention

Running multiple Monte Carlo simulations at various thermodynamic conditions can be automated by:

  • using the run_series() method to run a series of simulations along a path in conditions space,

  • using the casm-flow <TODO> package, which helps automate the process of setting up input files, submitting jobs to a cluster, and collecting, analyzing, and plotting results.