`pysimm.cassandra`¶

Module Contents¶

Classes¶

`MCSimulation`	pysimm.cassandra.MCSimulation
`GCMC`	pysimm.cassandra.GCMC
`NVT`	pysimm.cassandra.NVT
`NPT`	pysimm.cassandra.NPT
`InpSpec`	pysimm.cassandra.InpSpec
`InpProbSpec`	pysimm.cassandra.InpSpec
`McSystem`	pysimm.cassandra.McSystem
`Cassandra`	pysimm.cassandra.Cassandra
`McfWriter`	pysimm.cassandra.McfWriter

Functions¶

`check_cs_exec`()	pysimm.cassandra.check_cs_exec
`make_iterable`(obj)	pysimm.cassandra.make_iterable

Attributes¶

`DATA_PATH`
`KCALMOL_2_K`
`CASSANDRA_EXEC`
`DEFAULT_PARAMS`

pysimm.cassandra.DATA_PATH[source]¶

pysimm.cassandra.KCALMOL_2_K = 503.22271716452[source]¶

pysimm.cassandra.CASSANDRA_EXEC[source]¶

pysimm.cassandra.DEFAULT_PARAMS[source]¶

class pysimm.cassandra.MCSimulation(mc_sst=None, init_sst=None, **kwargs)[source]¶

Bases: object

pysimm.cassandra.MCSimulation

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

write(self)[source]¶

pysimm.cassandra.MCSimulation.write

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

group_by_id(self, group_key='matrix')[source]¶

pysimm.cassandra.MCSimulation.group_by_id

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:

matrix – (default) indexes of the atoms in fxd_sst
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
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(self)[source]¶

pysimm.cassandra.MCSimulation.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.

__check_params__(self)[source]¶

pysimm.cassandra.MCSimulation.__check_params__

Private method designed for update the fields of the simulation object to make them conformed with each other

__write_chk__(self, out_file)[source]¶

pysimm.cassandra.MCSimulation.__write_chk__

Creates the CASSANDRA checkpoint file basing on the information from the ~MCSimulation.tot_sst field

get_prp(self)[source]¶

class pysimm.cassandra.GCMC(mc_sst=None, init_sst=None, **kwargs)[source]¶

Bases: MCSimulation

pysimm.cassandra.GCMC 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.NVT(mc_sst=None, init_sst=None, **kwargs)[source]¶

Bases: MCSimulation

pysimm.cassandra.NVT 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.

class pysimm.cassandra.NPT(mc_sst=None, init_sst=None, **kwargs)[source]¶

Bases: MCSimulation

pysimm.cassandra.NPT 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.InpSpec(key, value, default, **kwargs)[source]¶

Bases: object

pysimm.cassandra.InpSpec

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(self)[source]¶

pysimm.cassandra.InpSpec.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.InpProbSpec(key, value, default, **kwargs)[source]¶

Bases: InpSpec

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(self)[source]¶

pysimm.cassandra.InpSpec.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.McSystem(sst, **kwargs)[source]¶

Bases: object

pysimm.cassandra.McSystem

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.

update_props(self, props)[source]¶

pysimm.cassandra.McSystem.update_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

update_frag_record(self, frag_record)[source]¶

pysimm.cassandra.McSystem.update_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
simulation ('Molecule_Files' property of the MC) –

Returns

updated dictionary

Return type

dictionary

make_system(self, text_output)[source]¶

pysimm.cassandra.McSystem.make_system

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

__fit_atoms__(self, molec, text_lines)[source]¶

pysimm.cassandra.McSystem.__fit_atoms__

Implements simple logic of comparison of the xyz-like text record with the System object. The comparison is based on the consecutive comparison of particle names and first letters (before the white space) in the text. In this implementation order matters! E.g. for CO2, if in the system atoms are ordered as C-O-O and in the text they are ordered like O-C-O fit will return False.

Returns: flag whether the text record fit the molecule or not
Return type: boolean

class pysimm.cassandra.Cassandra(init_sst)[source]¶

Bases: object

pysimm.cassandra.Cassandra

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

run(self)[source]¶

pysimm.cassandra.Cassandra.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.

add_simulation(self, ens_type, obj=None, **kwargs)[source]¶

pysimm.cassandra.Cassandra.add_simulation

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.

add_gcmc(self, obj=None, **kwargs)[source]¶

pysimm.cassandra.Cassandra.add_gcmc

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(self, obj=None, **kwargs)[source]¶

pysimm.cassandra.Cassandra.add_npt_mc

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(self, obj=None, **kwargs)[source]¶

pysimm.cassandra.Cassandra.add_nvt

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.

read_input(self, inp_file)[source]¶

pysimm.cassandra.Cassandra.read_input

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

__parse_value__(self, cells)[source]¶

unwrap_gas(self)[source]¶

pysimm.cassandra.Cassandra.unwrap_gas

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

class pysimm.cassandra.McfWriter(syst, file_ref)[source]¶

Bases: object

pysimm.cassandra.McfWriter

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

mcf_tags = ['# Bond_Info', '# Angle_Info', '# Dihedral_Info', '# Improper_Info', '# Intra_Scaling', '#...[source]¶

empty_line = 0[source]¶

write(self, typing='all')[source]¶

pysimm.cassandra.McfWriter.write

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’

__write_empty__(self, out, name)[source]¶

__write_atom_info__(self, out)[source]¶

__write_bond_info__(self, out)[source]¶

__write_angle_info__(self, out)[source]¶

__write_intra_scaling__(self, out)[source]¶

__write_dihedral_info__(self, out)[source]¶

__write_improper_info__(self, out)[source]¶

__write_fragment_info__(self, out)[source]¶

__write_fragment_connectivity__(self, out)[source]¶

__to_tags__(self, inpt)[source]¶

pysimm.cassandra.check_cs_exec()[source]¶

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)[source]¶

pysimm.cassandra.make_iterable

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

pysimm.cassandra¶

Module Contents¶

Classes¶

Functions¶

Attributes¶

`pysimm.cassandra`¶