pysimm.cassandra module

class pysimm.cassandra.Cassandra(init_sst)

Bases: object

Organizational object for running CASSANDRA simulation tasks. In current implementation it is able to run Canonical, Grand Canonical, and Isothermal-Isobaric Monte Carlo simulations (GCMC, NVT, and NPT, correspondingly).

Parameters:

• system (System) – molecular updated during the simulations
• run_queue (list) – the list of scheduled tasks

add_gcmc(obj=None, **kwargs)

Ads new simulation in grand-canonical ensemble to the run queue.

Parameters:

obj – the entity that should be added. Will be ignored if it is not of a type GCMC

Keyword Arguments:  

• is_new (boolean) – defines whether all previous simulations should be erased or not
• species (list of System) – systems that describe molecules and will be passed to McSystem constructor.

Note

Other keyword arguments of this method will be redirected to the McSystem, MCSimulation,

and GCMC constructors. See their descriptions for the possible keyword options.

add_npt_mc(obj=None, **kwargs)

Ads new simulation in isobaric-isothermal ensemble to the run queue.

Parameters:

obj – the entity that should be added. Will be ignored if it is not of a type NPT

Keyword Arguments:  

• is_new (boolean) – defines whether all previous simulations should be erased or not
• species (list of System) – systems that describe molecules and will be passed to McSystem constructor.

Note

Other keyword arguments of this method will be redirected to the McSystem, MCSimulation, and NPT constructors. See their descriptions for the possible keyword options.

add_nvt(obj=None, **kwargs)

Ads new simulation in canonical ensemble to the run queue.

Parameters:

obj – the entity that should be added. Will be ignored if it is not of a type NVT

Keyword Arguments:  

• is_new (boolean) – defines whether all previous simulations should be erased or not
• species (list of System) – systems that describe molecules and will be passed to McSystem constructor.

Note

Other keyword arguments of this method will be redirected to the McSystem, MCSimulation, and NVT constructors. See their descriptions for the possible keyword options.

add_simulation(ens_type, obj=None, **kwargs)

Method for adding new Monte Carlo simulation to the run queue.

Parameters:

• ens_type – Type of the molecular ensemble for the Monte-Carlo simulations. The supported options are: GCMC (Grand Canonical); NVT (canonical); NPT (isobaric-isothermal)
• obj – the entity that should be added. Will be ignored if it is not of a type MCSimulation

Keyword Arguments:  

• is_new (boolean) – defines whether all previous simulations should be erased or not
• species (list of System) – systems that describe molecules and will be passed to McSystem constructor.

Note

Other keyword arguments of this method will be redirected to the McSystem and MCSimulation constructors. See their descriptions for the possible keyword options.

read_input(inp_file)

The method parses the CASSANDRA instructions file (.inp) split it into separate instructions and analyses each according to the instruction name.

Parameters:inp_file (str) – the full relative path of the file to be read Returns:read CASSANDRA properties in the format required by GCMC Return type:dictionary

run()

Method that triggers the simulations. Does two consecutive steps: (1) tries to write all files necessary for simulation (.dat, .inp, .mcf): (2) tries to invoke the CASSANDRA executable.

unwrap_gas()

Ensures that all particles that are not fixed are unwrapped, otherwise CASSANDRA might not interpret them correctly

class pysimm.cassandra.GCMC(mc_sst=None, init_sst=None, **kwargs)

Bases: pysimm.cassandra.MCSimulation

Initiates the specific type of Monte Carlo simulations for CASSANDRA: simulations using Grand-Canonical ensemble of particles (constant volume-temperature-chemical potential, muVT). See MCSimulation for the detailed description of the properties.

class pysimm.cassandra.InpProbSpec(key, value, default, **kwargs)

Bases: pysimm.cassandra.InpSpec

Extension of the InpSpec class that takes into account special representation of the movement probabilities in the CASSANDRA input file.

to_string()

Creates the proper text representation of the property stored in the value field

Returns:formatted text string Return type:str

class pysimm.cassandra.InpSpec(key, value, default, **kwargs)

Bases: object

Represents the most common object used for carrying one logical unit of the CASSANDRA simulation options

Parameters:

• key (str) – the keyword of the simulation option (literally the string that goes after the # sign in CASSANDRA .inp file)
• value (object) – numerical or text values of the particular simulation option structured in a certain way. Here goes only the values that are wished to be changed (it might be just one field of a big dictionary)
• default (object) – the most complete default description of the simulation option

Keyword Arguments:  

• write_headers (boolean) – if the value is dictionary defines whether the dictionary keys should be written to the output
• new_line (boolean) – if the value is iterable defines whether each new element will be written to the new line

to_string()

Creates the proper text representation of the property stored in the value field

Returns:formatted text string Return type:str

class pysimm.cassandra.MCSimulation(mc_sst=None, init_sst=None, **kwargs)

Bases: object

Object containing the settings and the logic necessary to partially set-up an abstract Monte Carlo simulation to be submitted to the CASSANDRA software. The object also will include the simulation results once the simulations are finished.

mc_sst

describes all molecules to be inserted by CASSANDRA

Type:McSystem

init_sst

describes the optional initial fixed molecular configuration for MC simulations (default: empty cubic box with 1 nm side length). If the particles in the system are not attributed with the flag is_fixed all of them are considered to be fixed, and will be marked with this flag, otherwise all particles with is_fixed=False will be removed.

Type:System

Keyword Arguments:  

• out_folder (str) – the relative path of the simulation results (all .dat, .mcf, as well as .chk, … files will go there). If the folder does not exist it will be created with 0755 permissions.
• props_file (str) – the name of the .inp file.

Note

Other keyword arguments that are accepted are the GCMC simulation settings. The keywords of the settings are the same as they are described in CASSANDRA specification but without # symbol.

For example: the keyword argument Run_Name=’my_simulation’ will set #Run_Name setting in CASSANDRA input file to my_simulation value

Parameters:

• props (dictionary) – include all simulation settings to be written to the CASSANDRA .inp file
• input (str) – text stream that will be written to the CASSANDRA .inp file
• tot_sst (System) – object containing the results of CASSANDRA simulations

get_prp()

group_by_id(group_key='matrix')

Method groups the atoms of the system tot_sst by a certain property. Will iterate through all atoms in the system and return indexes of only those atoms that match the property. Currently supports 3 properties defined by the input keyword argument argument.

Keyword Arguments:  group_key (str) –

text constant defines the property to match. Possible keywords are:

1. matrix – (default) indexes of the atoms in fxd_sst
2. rigid – indexes of all atoms that have rigid atomic bonds. It is assumed here that rigid and nonrigid atoms can interact only through intermolecular forces
3. nonrigid – opposite of previous, indexes of all atoms that have nonrigid atomic bonds

Returns:string in format a1:b1 a2:b2 … where all indexes inside [ak, bk] belongs to the selected group and array of the form [[a1, b1], [a2, b2], …] Return type:str

upd_simulation()

Updates the tot_sst field using the MCSimulation.props[‘Run_Name’].chk file. Will try to parse the checkpoint file and read the coordinates of the molecules inserted by CASSANDRA. If neither of the molecules from the mc_sst can be fit to the text that was read the method will raise an exception. The fitting method: make_system assumes that different molecules inserted by CASSANDRA have the same order of the atoms.

write()

Iterates through the props dictionary creating the text for correct CASSANDRA input

class pysimm.cassandra.McSystem(sst, **kwargs)

Bases: object

Wrapper around the list of System objects. Each element in the list represents single molecule of a different specie that will be used during MC simulations. Additionally, the object is responsible for creating .dat and .mcf files needed for the simulation and reading back the CASSANDRA simulation results.

sst

items representing single molecules of different species to be inserted by CASSANDRA. If the sst is a list (not a single value) it is assumed that all of the following properties are synchronized with it by indexes.

Type:list of System

chem_pot

chemical potential for each specie [Joule/mol]

Type:list of int

Keyword Arguments:  

• max_ins (list of int) – defines the highest possible number of molecules of corresponding specie. Basing on these values CASSANDRA allocates memory for simulations. (default: 5000).
• is_rigid (list of boolean) – defines whether the atoms in the particular molecule should be marked as rigid or not. Important! In current implementation the module doesn’t support flexible molecule angles, so the is_rigid=False is designed to be used exclusively for single bead molecules.

Parameters:

• made_ins (list of int) – number of particles of each specie inserted by CASSANDRA.
• mcf_file (list of str) – defines full relative names of molecule configuration files (.mcf) required by CASSANDRA. Files will be created automatically.
• frag_file (list of str) – defines full relative names of possible relative configuration files (.dat) required by CASSANDRA. Files will be created automatically.

make_system(text_output)

Parses the checkpoint (.chk) file made by CASSANDRA and creates new molecules basing on the new coordinates information. Assumes that all atoms of a certain molecule are listed in .chk file together (molecule identifiers are not mixed).

Note

The logic of comparison of the xyz-like text record from the .chk file with the System object is most straightforward: It is the consecutive comparison of particle names and first letters (before the white space) in the text record. In this implementation order matters! For example, for CO2, if in the system atoms are ordered as C-O-O and in the text they are ordered as O-C-O fit will fail.

Parameters:text_output (str) – text stream from the CASSANDRA .chk file containing the coordinates of newly inserted molecules Returns:object containing all newly inserted molecules Return type:System

update_frag_record(frag_record)

For each specie in the system creates the single configuration .dat file required for CASSANDRA simulation.

Parameters:

• frag_record – dictionary containing the .dat file names and their ids. The dictionary is to be assigned to
• property of the MC simulation ('Molecule_Files') –

Returns:

updated dictionary

Return type:

dictionary

update_props(props)

For each specie in the system creates the .mcf file required for CASSANDRA simulation.

Parameters:props (dictionary) – contains the .mcf file names and maximally allowed number of molecules insertions. The dictionary is to be assigned to ‘Molecule_Files’ property of the MC simulation Returns:updated input dictionary Return type:props

class pysimm.cassandra.McfWriter(syst, file_ref)

Bases: object

Object responsible for creating the CASSANDRA Molecular Configuration file (.mcf).

syst

represents the molecule to be described

Type:System

file_ref

full relative path to the file that will be created

Type:str

empty_line = '0'

mcf_tags = ['# Atom_Info', '# Bond_Info', '# Angle_Info', '# Dihedral_Info', '# Improper_Info', '# Intra_Scaling', '# Fragment_Info', '# Fragment_Connectivity']

write(typing='all')

Method creates the .mcf file writing only those sections of it that are marked to be written

Parameters:typing (list) – the list of sections to be written or the text keyword. List items should be as they are defined in mcf_tags field); default ‘all’

class pysimm.cassandra.NPT(mc_sst=None, init_sst=None, **kwargs)

Bases: pysimm.cassandra.MCSimulation

Initiates the specific type of Monte Carlo simulations for CASSANDRA: simulations using Isobaric-Isothermal ensemble of particles (NPT). See MCSimulation for the detailed description of the properties.

class pysimm.cassandra.NVT(mc_sst=None, init_sst=None, **kwargs)

Bases: pysimm.cassandra.MCSimulation

Initiates the specific type of Monte Carlo simulations for CASSANDRA: simulations using Canonical ensemble of particles (constant volume-temperature-number of particles, NVT). See MCSimulation for the detailed description of the properties.

pysimm.cassandra.check_cs_exec()

Validates that the absolute path to the CASSANDRA executable is set in the CASSANDRA_EXEC environmental variable of the OS. The validation is called once inside the run method.

pysimm.cassandra.make_iterable(obj)

Utility method that forces the attributes be iterable (wrap in a list if it contains of only one item)