API Documentation

class mosdef_cassandra.System(boxes, species_topologies, mols_in_boxes=None, mols_to_add=None, fix_bonds=True)[source]
__init__(boxes, species_topologies, mols_in_boxes=None, mols_to_add=None, fix_bonds=True)

A class to contain the system to simulate in Cassandra

A System comprises the initial simulation box(es) (empty or occupied), the topologies of each species to be simulated, and the number of each species to be added to the simulation box(es) prior to the start of the simulation. These three items are represented by boxes, species_topologies, and mols_to_add. If providing a box with existing species, you are required to specify mols_in_boxes, the number of each species that already exists.

Each argument is specified as a list, with either one element for each box or one element for each species. Arguments must be provided as a list even in the case of a single species or single box.

Parameters

  • boxes (list) – one element per box. Each element should be a mbuild.Compound or mbuild.Box

  • species_topologies (list) – list of parmed.Structures, with one species per element

  • mols_in_boxes (list, optional) – one element per box. Each element is a list of length n_species, specifying the number of each species that are currently in each box

  • mols_to_add (list, optional) – one element per box. Each element is a list of length n_species, specifying the number of each species that should be added to each box

  • fix_bonds (boolean, optional, default=True) – update the bond lengths in any initial structure (i.e., boxes) to match the values specified in the species_topologies

Return type

mosdef_cassandra.System

property boxes
check_natoms()

Confirm that the number of existing atoms in each box agrees with the number of atoms specified from the combination of the number of atoms in each species and the number of each species in the box.

fix_bonds()

Apply the bond length constraints to each molecule in the system

property mols_in_boxes
property mols_to_add
property species_topologies
class mosdef_cassandra.MoveSet(ensemble, species_topologies)[source]
__init__(ensemble, species_topologies)

A class to contain all the move probabilities and related values required to perform a simulation in Cassandra.

A MoveSet contains the move probabilities and other related quantities (e.g., max translation/rotation) that are required to run Cassandra. When the MoveSet is created the specified ensemble and species_topologies are used to generate initial guesses for all required values. Depending upon the specifics of your system, these guesses may be very reasonable or downright terrible. Use the same species_topologies for your call to mosdef_cassandra.System() and mosdef_cassandra.MoveSet().

Parameters

  • ensemble (str) – string describing the desired ensembled. Supported values include 'nvt', 'npt', 'gcmc', 'gemc', 'gemc_npt'

  • species_topologies (list) – list of parmed.Structures, with one species per element

Return type

mosdef_cassandra.MoveSet

add_restricted_insertions(species_topologies, restricted_type, restricted_value)

Add restricted insertions for specific species and boxes

Parameters

  • species_topologies (list) – list of parmed.Structures containing one list per box of species

  • restricted_type (list) – list of restricted insertion types containing one list per box of species

  • restricted_value (list) – list of restricted insertion values (unyt arrays) containing one list per box of species

property cbmc_n_dihed
property cbmc_n_insert
property cbmc_rcut
property ensemble
property insertable
property max_dihedral
property max_rotate
property max_translate
property max_volume
print()

Print the current contents of the MoveSet

property prob_angle
property prob_dihedral
property prob_insert
property prob_regrow
property prob_regrow_species
property prob_rotate
property prob_swap
property prob_swap_from_box
property prob_swap_species
property prob_translate
property prob_volume
mosdef_cassandra.run(system, moveset, run_type, run_length, temperature, **kwargs)[source]

Run the Monte Carlo simulation with Cassandra

The following steps are performed: write the molecular connectivity files for each species to disk, write the starting structures (if any) to disk, generate and write the Cassandra input file to disk, call Cassandra to generate the required fragment libraries, and call Cassandra to run the MC simulation.

Parameters

  • system (mosdef_cassandra.System) – the System to simulate

  • moveset (mosdef_cassandra.MoveSet) – the MoveSet to simulate

  • run_type (“equilibration” or “production”) – the type of run; in “equilibration” mode, Cassandra adaptively changes the maximum translation, rotation, and volume move sizes to achieve an acceptance ratio of 0.5

  • run_length (int) – length of the MC simulation

  • temperature (float) – temperature at which to perform the MC simulation

  • **kwargs (keyword arguments) – any other valid keyword arguments, see mosdef_cassandra.print_valid_kwargs() for details

mosdef_cassandra.restart(total_run_length=None, restart_from=None, run_name=None, run_type=None)[source]

Restart a Monte Carlo simulation from a checkpoint file with Cassandra

The function requires the following in the working directory. These items would have all been generated for the original run:

  • Cassandra input (.inp) file named {restart_from}.inp

  • Cassandra checkpoint file (.chk) name {restart_from}.out.chk

  • MCF files for each species

  • Fragment libraries for each species

The maximum translation, rotation, and volume move sizes are read from the checkpoint file. Similarly, the starting structure is taken from the checkpoint file. If the “restart_name” is not provided or if the “run_name” is the same as “restart_name”, “.rst.N” will be appended to the “run_name”.

If you wish to extend a simulation you will need to specify the _total_ number of simulation steps desired with the total_run_length option. For example, if your original run was 1e6 MC steps, but you wish to extend it by an additional 1e6 steps, use total_run_length=2000000.

Parameters

  • total_run_length (int, optional, default=None) – total length of the MC simulation; if None, use original simulation length

  • restart_from (str, optional, default=None) – name of run to restart from; if None, searches current directory for Cassandra inp files

  • run_name (str, optional, default=None) – name of this run; if None, appends “.rst.NNN.” to run_name, where “NNN” is the restart iteration “001”, “002”, …,

  • run_type (str, “equilibration” or “production”, default=None) – the type of run; in “equilibration” mode, Cassandra adaptively changes the maximum translation, rotation, and volume move sizes to achieve an acceptance ratio of 0.5. If None, use the same choice as the previous run.

mosdef_cassandra.print_valid_kwargs()[source]

Print the valid keyword arguments with a brief description

mosdef_cassandra.print_inputfile(system, moveset, run_type, run_length, temperature, **kwargs)[source]

Print an example Cassandra input file to screen

This function allows one to look at the Cassandra input file that will be generated without running the MC simulation. The arguments are identical mosdef_cassandra.run

Parameters

  • system (mosdef_cassandra.System) – the System to simulate

  • moveset (mosdef_cassandra.MoveSet) – the Move set to simulate

  • run_type (“equilibration” or “production”) – the type of run; in “equilibration” mode, Cassandra adaptively changes the maximum translation, rotation, and volume move sizes to achieve an acceptance ratio of 0.5

  • run_length (int) – length of the MC simulation

  • temperature (float) – temperature at which to perform the MC simulation

  • **kwargs (keyword arguments) – any other valid keyword arguments, see mosdef_cassandra.print_valid_kwargs() for details

class mosdef_cassandra.analysis.ThermoProps(filename)[source]

Store thermodynamic properties from a Cassandra .prp file

__init__(filename)

Create ThermoProps from a .prp file

Parameters

filename (string) – path to the .prp file

Returns

object containing the contents of the .prp file

Return type

ThermoProps

property filename
print_props()

Print the available properties

prop(prp_name, start=None, end=None, units=True)

Extract the specified property

Parameters

  • prp_name (string) – the property to extract

  • start (int) – the starting step/sweep/etc.

  • end (int) – the ending step/sweep/etc.

Returns

the property with units

Return type

unyt_array

to_df()

Convert ThermoProps to a pandas.DataFrame