API documentation

pymatgen Modules

Units

class pymatgen_core.core.units.ArrayWithUnit(input_array, unit, unit_type=None)

Bases: numpy.ndarray

Subclasses numpy.ndarray to attach a unit type. Typically, you should use the pre-defined unit type subclasses such as EnergyArray, LengthArray, etc. instead of using ArrayWithFloatWithUnit directly.

Supports conversion, addition and subtraction of the same unit type. E.g., 1 m + 20 cm will be automatically converted to 1.2 m (units follow the leftmost quantity).

>>> a = EnergyArray([1, 2], "Ha")
>>> b = EnergyArray([1, 2], "eV")
>>> c = a + b
>>> print(c)
[ 1.03674933  2.07349865] Ha
>>> c.to("eV")
array([ 28.21138386,  56.42276772]) eV
Error

alias of UnitError

property as_base_units

Returns this ArrayWithUnit in base SI units, including derived units.

Returns:

An ArrayWithUnit object in base SI units

conversions()

Returns a string showing the available conversions. Useful tool in interactive mode.

property supported_units

Supported units for specific unit type.

to(new_unit)

Conversion to a new_unit.

Args:
new_unit:

New unit type.

Returns:

A ArrayWithFloatWithUnit object in the new units.

Example usage: >>> e = EnergyArray([1, 1.1], “Ha”) >>> e.to(“eV”) array([ 27.21138386, 29.93252225]) eV

pymatgen_core.core.units.Charge = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='charge')

A float with a charge unit.

Args:

val (float): Value unit (Unit): E.g., C, e (electron charge). Must be valid unit or UnitError is raised.

pymatgen_core.core.units.Density = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='density')

A float with a density unit.

Args:

val (float): Value unit (Unit): E.g., eV, kJ, etc. Must be valid unit or UnitError is raised.

pymatgen_core.core.units.Energy = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='energy')

A float with an energy unit.

Args:

val (float): Value unit (Unit): E.g., eV, kJ, etc. Must be valid unit or UnitError is raised.

class pymatgen_core.core.units.FloatWithUnit(val, unit, unit_type=None)

Bases: float

Subclasses float to attach a unit type. Typically, you should use the pre-defined unit type subclasses such as Energy, Length, etc. instead of using FloatWithUnit directly.

Supports conversion, addition and subtraction of the same unit type. E.g., 1 m + 20 cm will be automatically converted to 1.2 m (units follow the leftmost quantity). Note that FloatWithUnit does not override the eq method for float, i.e., units are not checked when testing for equality. The reason is to allow this class to be used transparently wherever floats are expected.

>>> e = Energy(1.1, "Ha")
>>> a = Energy(1.1, "Ha")
>>> b = Energy(3, "eV")
>>> c = a + b
>>> print(c)
1.2102479761938871 Ha
>>> c.to("eV")
32.932522246000005 eV
Error

alias of UnitError

property as_base_units

Returns this FloatWithUnit in base SI units, including derived units.

Returns:

A FloatWithUnit object in base SI units

classmethod from_string(s)

Initialize a FloatWithUnit from a string. Example Memory.from_string(“1. Mb”)

property supported_units

Supported units for specific unit type.

to(new_unit)

Conversion to a new_unit. Right now, only supports 1 to 1 mapping of units of each type.

Args:

new_unit: New unit type.

Returns:

A FloatWithUnit object in the new units.

Example usage: >>> e = Energy(1.1, “eV”) >>> e = Energy(1.1, “Ha”) >>> e.to(“eV”) 29.932522246 eV

pymatgen_core.core.units.Length = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='length')

A float with a length unit.

Args:

val (float): Value unit (Unit): E.g., m, ang, bohr, etc. Must be valid unit or UnitError is raised.

pymatgen_core.core.units.Mass = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='mass')

A float with a mass unit.

Args:

val (float): Value unit (Unit): E.g., amu, kg, etc. Must be valid unit or UnitError is raised.

pymatgen_core.core.units.Memory = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='memory')

A float with a memory unit.

Args:

val (float): Value unit (Unit): E.g., Kb, Mb, Gb, Tb. Must be valid unit or UnitError is raised.

class pymatgen_core.core.units.ObjectUnits(unit_conf=<property object>)

Bases: monty.json.MSONable

Object with properties that have units

The value of the properties with units are stored in the _property dictionary with a key that is the name of the property. The unit type of the property is stored in the _property_units dictionary where each unit type has a list of the property keys of that type.

Kwargs:
  • unit_conf (dict): Unit types with units used by this object

update_units(new_unit_conf)

Update instance values with new units

Args:
  • new_unit_conf (dict): with unit type as the key and the new unit as the value

pymatgen_core.core.units.Temp = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='temperature')

A float with a temperature unit.

Args:

val (float): Value unit (Unit): E.g., K. Only K (kelvin) is supported.

pymatgen_core.core.units.Time = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='time')

A float with a time unit.

Args:

val (float): Value unit (Unit): E.g., s, min, h. Must be valid unit or UnitError is raised.

class pymatgen_core.core.units.Unit(unit_def)

Bases: collections.abc.Mapping

Represents a unit, e.g., “m” for meters, etc. Supports compound units. Only integer powers are supported for units.

Error

alias of UnitError

property as_base_units

Converts all units to base SI units, including derived units.

Returns:

(base_units_dict, scaling factor). base_units_dict will not contain any constants, which are gathered in the scaling factor.

get_conversion_factor(new_unit)

Returns a conversion factor between this unit and a new unit. Compound units are supported, but must have the same powers in each unit type.

Args:

new_unit: The new unit.

exception pymatgen_core.core.units.UnitError

Bases: BaseException

Exception class for unit errors.

pymatgen_core.core.units.Volume = functools.partial(<class 'pymatgen_core.core.units.FloatWithUnit'>, unit_type='volume')

A float with an volume unit.

Args:

val (float): Value unit (Unit): E.g., eV, kJ, etc. Must be valid unit or UnitError is raised.

pymatgen_core.core.units.bohr_to_ang = 0.529177210903

Definitions of supported units. Values below are essentially scaling and conversion factors. What matters is the relative values, not the absolute. The SI units must have factor 1.

pymatgen_core.core.units.change_properties_units(old_unit_conf, new_unit_conf, property_units, properties)

Update instance values with new units

Args:
  • old_unit_conf (dict): with unit type as the key and the new unit as the value

  • new_unit_conf (dict): with unit type as the key and the new unit as the value

  • property_units (dict):

  • properties (dict): with unit type as the key and the new unit as the value

pymatgen_core.core.units.logger = <Logger pymatgen_core.core.units (DEBUG)>

Some conversion factors

pymatgen_core.core.units.obj_with_unit(obj, unit)

Returns a FloatWithUnit instance if obj is scalar, a dictionary of objects with units if obj is a dict, else an instance of ArrayWithFloatWithUnit.

Args:

unit: Specific units (eV, Ha, m, ang, etc.).

pymatgen_core.core.units.unitized(unit)

Useful decorator to assign units to the output of a function. You can also use it to standardize the output units of a function that already returns a FloatWithUnit or ArrayWithUnit. For sequences, all values in the sequences are assigned the same unit. It works with Python sequences only. The creation of numpy arrays loses all unit information. For mapping types, the values are assigned units.

Args:

unit: Specific unit (eV, Ha, m, ang, etc.).

Example usage:

@unitized(unit="kg")
def get_mass():
    return 123.45

Lattice

class pymatgen_core.core.lattice.Lattice(matrix=[100.0, 0.0, 0.0, 0.0, 100.0, 0.0, 0.0, 0.0, 100.0], unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

A lattice object. Essentially a matrix with conversion matrices. In general, it is assumed that length units are in Angstroms and angles are in degrees unless otherwise stated.

constants2matrix(a, b, c, alpha_r, beta_r, gamma_r)

Calculate the matrix based on the lattice constants

Args:
  • a (float): lattice constant a

  • b (float): lattice constant b

  • c (float): lattice constant c

  • alpha (float): lattice angle alpha in radians

  • beta (float): lattice angle beta in radians

  • gamma (float): lattice angle gamma in radians

copy()

Deep copy of self.

d_pos(pos_i, pos_j)

Difference between two positions

Args:
  • pos_i (list): cartesian coordinates [x,y,z] for position i

  • pos_j (list): cartesian coordinates [x,y,z] for position j

Returns:
  • dr_ij (list): cartesian vector [x,y,z] between position i and j

If pbcs are set to true this calculates the fractional coordinates according to the inverse of the matrix multiplied by the position

\[F = P M^{-1}\]

Then subtractions the fractional coordinates and rounds them to be within the lattice box. Then translates the fractional coordinates back to real coordinates to get the separation vector

delta_npos(npos_i, npos_j)

Difference between two position lists in cubic lattice

Args:
  • pos_i (list of lists): list of cartesian coordinates [x,y,z] for positions i

  • pos_j (list of lists): list of cartesian coordinates [x,y,z] for positions j

Returns:
  • npos_ij (m x n numpy array): array of cartesian vector [x,y,z] between position i and j where the npos_ij[i][j] value is the difference between pos_i[i] and pos_j[j]

  • mag_dr_ij (m x n numpy array): array of the magnitudes of vector dr_ij where the mag_dr_ij[i][j] value is the distance between pos_i[i] and pos_j[j]

delta_pos(pos_i, pos_j)

Difference between two positions

Args:
  • pos_i (list): cartesian coordinates [x,y,z] for position i

  • pos_j (list): cartesian coordinates [x,y,z] for position j

Returns:
  • dr_ij (list): cartesian vector [x,y,z] between position i and j

  • mag_dr_ij (float): magnitude of vector dr_ij

expand_matrix(exlat_frac)

Increase size of lattice by certain fraction

Args:
  • exlat_frac (float): fraction to increase lattice by

export_json(tag, write_file=True)

Export object to json

Args:
  • tag (str) ID of file to be written

Kwargs:
  • write_file (boolean) to dump json to a file

Returns:
  • json_data (dict) json representation of the object

fractoreal(frac_o)

Translate fractional coordinates to real

Args:
  • frac_o (numpy array): fraction coordinates

Returns:
  • pos_o (numpy array): real cartesian coordinates

get_rad_angles()

Return angles in radians

import_json(tag, json_data={}, read_file=True)

Export object to json

Args:
  • tag (str) ID of file to be read

Kwargs:
  • read_file (boolean) to read json from a file

  • json_data (dict) json representation of the object

norm_d_pos(pos_i, pos_j)

Normalized difference between two positions in cubic lattice

Args:
  • pos_i (list): cartesian coordinates [x,y,z] for position i

  • pos_j (list): cartesian coordinates [x,y,z] for position j

Returns:
  • dr_ij (list): normalized cartesian vector [x,y,z] between position i and j

proximitycheck(npos_i, npos_j, pos_cut, p=None)

Difference between two position lists in cubic lattice

Args:
  • pos_i (list of lists): list of cartesian coordinates [x,y,z] for positions i

  • pos_j (list of lists): list of cartesian coordinates [x,y,z] for positions j

Returns:
  • True: if no overlap between particles was found

  • False: if overlap between particles was found

random_pos()

Generate random position in lattice.

Assume random.seed(seed) has been initialized

set_cubic(len_o)

Set lattice to cubic with lattice constant

Args:
  • len_o (float): Length of cubic lattice constant a

Structures Module

Structure Components

class streamm.structures.particle.Particle(type='atom', label=None, symbol=None, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Data structure for describing any localized object in QM/MD simulation, such as an atom.

Kwargs:
  • type (str): Particle type

  • label (str): Identifier in output files

  • symbol (str): Atomic symbol

  • unit_conf (dict): Unit types with units used by this object

Particles have fundamental attributes which are used throughout the streamm code:

mass(float)

Mass of the particle

charge(float)

Charge of the particle in e

bonded_radius(float)

Radius in used in determining if two particles are bonded

nonbonded_radius(float)

Radius in used in determining if two particles are interacting

Additional attributes include:

mol(int)

Molecule index

ring(int)

Ring index

residue(int)

Residue index

resname(str)

Residue name

qgroup(int)

Charge group index

index(int)

Index of particle in particle dictionary

ffkey(str)

Particletype key

The element attribute can be set to an element object from the periodic_table object in pymatgen.

The ff attribute can be set to a Particletype object.

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

set_element(symbol=None, number=None, mass=None, mass_precision=0)

Set the element of property of the particle

Kwargs:
  • symbol (str): Atomic symbol.

  • number (int): Atomic number

  • mass (float): Atomic mass (AMU)

  • mass_precision (int): precision to match the mass with value from periodic table

This will set the symbol property of the particle to the Atomic symbol, the mass property of the particle to the atomic_mass, the bonded_radius property of the particle to the atomic_radius_calculated and the nonbonded_radius property of the particle to the van_der_waals_radius

show_attributes()

Like __str__ but with all the values of the instance’s attributes

class streamm.structures.bond.Bond(pkey1, pkey2, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Data structure for describing any 2-point association of Particles

Args:
  • pkey1 (int): Index of Particle i.

  • pkey2 (int): Index of Particle i.

Kwargs:
  • units_conf (dict): Dictionary of units for each attribute type

length(float)

length of the bond unit type (length)

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

class streamm.structures.angle.Angle(pkey1, pkey2, pkey3, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Data structure for describing any 3-point associations of Particles

Args:
  • pkey1 (int): Index of Particle object in angle

  • pkey2 (int): Index of Particle object in angle

  • pkey3 (int): Index of Particle object in angle

Kwargs:
  • unit_conf (dict): Unit types with units used by this object

cosine(float)

Cosine of the bond angle

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

class streamm.structures.dihedral.Dihedral(pkey1, pkey2, pkey3, pkey4, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Data structure for describing any 4-point associations of Particles

Args:
  • pkey1 (int) Index of Particle object in dihedral

  • pkey2 (int) Index of Particle object in dihedral

  • pkey3 (int) Index of Particle object in dihedral

  • pkey4 (int) Index of Particle object in dihedral

Kwargs:
  • units_conf (dict): Dictionary of units for each attribute type

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

class streamm.structures.improper.Improper(pkey1, pkey2, pkey3, pkey4, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Data structure for describing any 4-point association of Particles

Args:
  • pkey1 (int) Dictionary key of Particle object in improper

  • pkey2 (int) Dictionary key of Particle object in improper

  • pkey3 (int) Dictionary key of Particle object in improper

  • pkey4 (int) Dictionary key of Particle object in improper

Kwargs:
  • units_conf (dict): Dictionary of units for each attribute type

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

Group

class streamm.structures.group.Group(strucC, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Sets of particles within a structureContainer

Args:
  • strucC (structures.container.Container): Reference structure Container

Kwargs:
  • units_conf (dict): Dictionary of units for each attribute type

calc_asphericity()

Calculate the eigen values of the gyration tensor and the asphericity,

calc_dl()

Calculate the maximum end to end distance.

calc_radius()

Calculate the maximum radius and radius of gyration (r_gy_sq)

centerofmass()

Calculate the center of mass

hterm_group(debug=False)

Hydrogen terminate group

(j)    (l)
    -  /
    (i)    - 109.5 deg
    /  -
(k)     (m)

Hydrogens will be added to sp3 carbons in a tetrahedral configuration

     ^         (l)
     |        /  |
A    |   C  /    |
     |    /      |
     |  /        |
     (i) -------->
           B

If particle i is bonded to two other particles j and k

\[r_{ij} = position_i - position_j\]
\[r_{ik} = position_i - position_k\]
\[A = r_{ij} x r_{ik}\]
\[B = r_ij + r_ik\]

For the angle l - i - m to be 109.5

\[|A| = sin( 109.5/2 ) |C|\]
\[|B| = cos( 109.5/2 ) |C|\]

By scaling A and B they can be added to get the bonds between i and l and m

\[r_{il} = A + B\]
\[r_{im} = -A + B\]

Choose vector cros_ik normal to plane of i,j and one neighbor of j

     cros_ik    H0
      |        /
      |       /
      j ---- i
    /
   /
jk

Scale vectore cros_ik by sin(109.5)

         H1
        /
       /
j----i  ----  dr_CC_s

add to vector dr_CC between i-j scaled by cos(109.5) to get a vector hbond_0 which has an angle j-i-H0 of 109.5

             H1
theta=109.5 /
           /
    j----i ---- H0
           -
            -
             -
              H2

so dr_CC_s is the same as H0

    H0(cros_ik_n)
    |
    |    theta2 = 120.0
    |
    i  -------cros_jk
   /  -
  /    -
 /      -
H2       H1

H1 is at 2pi/3 from cros_ik_n and cros_jk H2 is at -2pi/3 from cros_ik_n and cros_jk

and cros_ijk_n is again scaled by sin[109.5]

write_coord()

Write coordinates into string

write_xyz(xyz_file='')

Write the particles of the group to an xyz file

Kwargs:
  • xyz_file (str): xyz file tag

class streamm.structures.group.Groups(tag, strucC, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Set of groups within a structure.containers.Container

Args:
  • tag (str): Identifier of collection of groups

  • strucC (structures.container.Container): Reference structure Container

calc_cent_mass()

Calculate center of mass of groups and store them in list

calc_dl()

Calculate the maximum end to end distance of each group

calc_radius()

Calculate radius of groups and store them in list

calc_radius_asphericity()

Calculate radius of groups and store them in list

dr_particles(g_i, g_j, r_cut, sub_list=[])

Find a list of the distances between particles of two group members

export_json(write_file=True)

Export particles to json

Kwargs:
  • write_file (boolean) to dump json to a file

Returns:
  • json_data (dict) json representation of the object

find_pairs(list_i, list_j, mol_inter=False, mol_intra=False)

Find pairs based on criteria

Args:
  • list_i (list) list of particle index

  • list_j (list) list of particle index

  • mol_inter (Boolean) include inter-molecular connections

  • mol_intra (Boolean) include intra-molecular connections

group_pbcs(accuracy=4)

Apply PBC’s to create whole groups

Assumes group length is shorter than box length

group_prop(prop, tag, particles_select=[])

Create groups of mols or residues

Args:
  • prop (str): property key

  • tag (str): key for Groups object in groups dict

Kwargs:
  • particles_select (list): list of particle keys to be included in groups

    defaults to all particles.keys if none are specified

guess_nblist(radius_type, radii_buffer=1.25)

Create neighbor list of particles based on distance and element.covalent_radius of each particle

Args:
  • radius_type (int)
    • 0 - element.covalent_radius

    • 1 - element.vdw_radius

  • radii_buffer (float) to multiply radii cut off

Return:
  • NBlist (object)

import_json(json_data={}, read_file=True)

Export object to json

Kwargs:
  • json_lattice (dict) json representation of the object

  • read_file (boolean) to read json from a file

update_units(new_unit_conf)

Update instance values with new units

Args:
  • new_unit_conf (dict): with unit type as the key and the new unit as the value

write_cm_xyz(group_file='')

Write center of mass of each group into an xyz file

write_xyzs()

Write group coordinates into an xyz file

Neighbor List

class streamm.structures.nblist.NBlist

Bases: object

Class for neighbor list.

list(list)

list of all neighboring indexes in sequence

index(list)

list of the location in list of the beginning of the neighbors sequence

Example: You have ethane with particle labels of C1, H1, H2, H3, C2, H4, H5 and H6- with particle indexes of 0, 1, 2, 3, 4, 5, 6 and 7 respectively.

   H1         H4
     -       /
H2 -- C1 -- C2 -- H5
     /       -
   H3         H6

You would have the following bonds:

  • C1[0] - C2[4]

  • C1[0] - H1[1]

  • C1[0] - H2[2]

  • C1[0] - H3[3]

  • C2[4] - H4[5]

  • C2[4] - H5[6]

  • C2[4] - H6[7]

The list would be [1, 2, 3, 4, 0, 0, 0, 0, 5, 6, 7, 4, 4, 4] and the index would be [0, 4, 5, 6, 7, 11, 12, 13, 14]. So if we want the neighbor indexes of C2 (particle 4), we get the beginning position in list from index[4] to be 7 and the ending position in list for index[7+1]-1 to be 10. So from the index we know C2 has the neighbors list[7:10] ([0, 5, 6, 7]), which are C1, H4, H5 and H6. The last value of 14 in the index list is to give the last position in the list for the last particle (index[7+1]-1).

calc_nnab(key_i)

Calculate the number of neighbors for particle key_i

Args:

key_i (int): Index of item in neighbor list

Returns:

(int): number of neighbors of key_i

getnbs(key_i)

Return list of in of neighbors of key_i

Args:

key_i (int): Index of item in neighbor list

Returns:

nb_list (list): list of indexes of neighbors of key_i

radii_nblist(lat, positions, radii, radii_buffer=1.25, write_dr=True, del_drmatrix=False)

Create neighbor list of positions based on distance and radius of each particle

Args:
  • lat (Lattice) object

  • positions (list) of particle position numpy arrays

  • radii (list) of radius of particle

Kwargs:
  • radii_buffer (float) to multiply radii cut off

  • write_dr (boolean)

  • del_drmatrix (boolean)

Structure Container

class streamm.structures.structure.Structure(tag='blank', matrix=[100.0, 0.0, 0.0, 0.0, 100.0, 0.0, 0.0, 0.0, 100.0], unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Data structure for describing a collection of Particles that have associated positions within a Lattice, and consistent set keys corresponding to Bond, Angle, Dihedral and Improper descriptions

Kwargs:
  • tag (str): Identifier for structure container

  • matrix (list): list of lattice vectors (v1,v2,v3) in order 1-3 with format: [v1(x),v1(y),v1(z),v2(x),v2(y),v2(z),v3(x),v3(y),v3(z)]

  • units_conf (dict): Dictionary of units for each attribute type

mass(float)

Sum of the mass of particles in the structure

charge(charge)

Sum of the charge of particles in the structure

volume(float)

Volume of the structure based on the lattice

density(float)

Density of the structure

center_mass(numpy array)

Center of mass of the structure

dipole(numpy array)

Electric dipole moment

positions(numpy array)

Positions of particles in structure

Todo

Update max_mol to n_mol

add_angle(angle_i, deepcopy=True)

Add ‘Angle’ object to angles dict in this container and update n_angles accordingly

add_bond(bond_i, deepcopy=True)

Add ‘Bond’ object to bonds dict in this container and update n_bonds accordingly

add_dihedral(dihedral_i, deepcopy=True)

Add ‘Dihedral’ object to dihedrals dict in this container and update n_dihedrals accordingly

add_improper(improper_i, deepcopy=True)

Add ‘Improper’ object to impropers dict in this container and update n_impropers accordingly

add_particle(particle_i, deepcopy=True)

Add ‘Particle’ object to this container and update n_particles accordingly

add_partpos(particle_i, pos_i, deepcopy=True)
Add ‘Particle’ object to this container and update n_particles accordingly and

append ‘position’ array to this container.

add_position(pos_i)

Append ‘position’ as numpy array to this container.

add_struc(other, n_i, seed, p=None, tag='blank')

Add structure other to self n times via random placement

add_struc_grid(other, n_i, p=None, tag='blank', calc_overlap=True)

Add structure other to self n times on a grid

Args:
  • n_i (int) number of times to replicate

bonded_angles()

Generate angles from bonded neighbor list

bonded_bonds()

Generate bonds from bonded neighbor list

bonded_dih()

Generate dihedrals from nbonded neighbor list

build_nblist()

Create neighbor list of bonded particles based on bonds in the container

Return:
  • NBlist (object)

calc_angle(angle_i)

Calculate the cosine theta between two vectors

calc_angles(keys=[])

Calculate the cosine theta between two vectors according to list_i and list_j

calc_bond(bond_i)

Calculate the distance between two vectors

Args:

bond_i (Bond) Bond object

calc_bonds(keys=[])

Calculate bond lengths all bond according to list of keys

calc_center_mass()

Find center of mass of a structure

calc_charge()

Calculate total charge of structure

calc_composition()

Calculate composition

calc_density()

Calculate density of structure

calc_dihedral(dihedral_i)

Calculate the dihedral angel

calc_dihedrals(keys=[])

Calculate the cosine theta of a dihedral angle according to keys

calc_elcnt(key_i, nb_list)

Calculate the number of each element type in the neighbors of particle key_i

Return:
  • el_cnt (list) count of each element at its atomic number index

Example: el_cnt[6] is the number of carbon neighbors

calc_formula()

Calculate chemical formula

calc_mass()

Calculate total mass of structure

calc_volume()

Calculate volume of structure

\[Volume = ( v_i x v_j ) * v_k\]
change_mass(symbol_o, mass_o)

Change the mass of the particles with a certain symbol to a certain number

Args:
  • symbol_o (str) symbol of particle to be changed

  • mass_o (float) new mass of particle with symbol symbol_o

del_particle(pkey)

Remove a particle from Container

distbin_pairs(list_i, list_j, pairvalue_ij, bin_size, r_cut, rank)

Bin distances between particle pairs

Add size to cutoff Assumes cut off is evenly divisible by bin_size

     |                      |
-bin_size/2.0   r_cut   +bin_size/2.0
dump_pickle()

Write Pickle object

export_json(write_file=True)

Export particles to json

Kwargs:
  • write_file (boolean) to dump json to a file

Returns:
  • json_data (dict) json representation of the object

find_angles(list_k=[], list_i=[], list_j=[])

Find angles according to list of particles

find_bonds(list_i=[], list_j=[])

Find bonds according to list of particles

find_dihedrals(list_k=[], list_i=[], list_j=[], list_l=[])

Find dihedrals according to list of particles

find_pairs(list_i, list_j, mol_inter=False, mol_intra=False)

Find pairs based on criteria

findbond_key(pid_i, pid_j)

Find key for bond with particles pid_i and pid_j

getSubStructure(pkeys, tag='blank')

Create new structure container from list of particle keys

get_list_angles_cosine(keys=[])

Get list from bonds of the properties length

get_list_bonds_lengths(keys=[])

Get list from bonds of the properties length

Kwargs:
  • keys (list) list of particle indexes

get_list_dihedral_cosine(keys=[])

Get list from bonds of the properties length

get_max()

get max mol, residue and charge group number

guess_nblist(radius_type, radii_buffer=1.25)

Create neighbor list of particles based on distance and element.covalent_radius of each particle

Args:
  • radius_type (int)
    • 0 - element.covalent_radius

    • 1 - element.vdw_radius

  • radii_buffer (float) to multiply radii cut off

Return:
  • NBlist (object)

import_json(json_data={}, read_file=True)

Export object to json

Kwargs:
  • json_lattice (dict) json representation of the object

  • read_file (boolean) to read json from a file

lat_cubic(len_o)

Set lattice to cubic with lattice constant len

maxtags()

Find max mol and residue numbers

mol_mult()

Find value to multiply mol index by so residue index can be added to get a unique group value

n_molecules()

Number of molecules

Todo

deprecate

pbc_pos()

Apply periodic boundary conditions to

print_properties()

Print the structure properties

proc_dihedrals(keys=[])

Calculate the dihedral angels from angle_list

propcompile_particles()

Compile all the properties of each particle into a single dictionary

read_xyz(xyz_file='')

Read a structure to an xmol file

Kwargs:
  • xyz_file (str) xyz file to read data from

rotate_xy(theta_xy, direction='counterclockwise')

Rotate around the z-axis in the xy plane

z        v_i
|       /
|      /
|    /
|  /
|/_______________ y
                                                                                 x
      _                                _
     |   cos theta_xy  sin theta_xy  0  |
Rz = |   -sin theta_xy  cos theta_xy  0  |
     |_         0           0        1 _|
Args:

theta_xy (float) angle in radians direction (str) counterclockwise or clockwise around z-axis

rotate_xz(theta_xz, direction='counterclockwise')

Rotate around the y-axis in the xz plane

Args:

theta_xz (float) angle in radians direction (str) counterclockwise or clockwise around y-axis

     |   cos theta_xz 0 -sin theta_xz   |
Ry = |           0    1      0         |
     |_  sin theta_xz 0  cos theta_xz _|
rotate_yz(theta_yz, direction='counterclockwise')

Rotate around the x-axis in the yz plane

z        v_i
|       /
|      /
|    /
|  /
|/_______________ y
                                                                                 x
       _                                    _
      |      1        0           0          |
Rx =  |      0  cos theta_xy  sin theta_xy   |
      |_     0  -sin theta_xy  cos theta_xy _|
Args:
  • theta_yz (float) angle in radians

  • direction (str) counterclockwise or clockwise around x-axis

shift(pkey, vec)

Shift position of pkey by vector

Arguments:
  • pkey (int) particle key

  • vec (numpy array) vector

shift_pos(vec)

Shift position of all particles by vecx

shift_tag(tag, tag_min)

shift tag by a number

sum_charge(pkey_i, pkey_j)

Sum charge of particle i into particle j

Args:
  • pkey_i (int) Particle key

  • pkey_j (int) Particle key

sum_prop(pkey_i, pkey_j)

Sum property of particle i into particle j

Args:
  • pkey_i (int) Particle key

  • pkey_j (int) Particle key

Todo

This should be changed to sum_charge

update_units(new_unit_conf)

Update instance values with new units

Args:
  • new_unit_conf (dict): with unit type as the key and the new unit as the value

write_angles(angles_file, keys=[])

Write out angles in csv file

write_bonds(bonds_file, keys=[])

Write out bonds in csv file

write_coord()

Write coordinates into string

write_dihedrals(dih_file, keys=[])

Calculate the dihedral angels from angle_list

write_list(list_i, tag_i)

Write list of particle keys to file to use in remote analysis

Args:
  • list_i (list): list of particle indexes

  • tag_i (str): string to be used as file name tag.list

write_xyz(xyz_file='')

Write a structure to an xyz file

Kwargs:
  • xyz_file (str) xyz file to write data to

write_xyz_list(list_i, xyz_file='')

Write a list of certain particles of the structure to an xyz file

Args:
  • list_i (list) list of particle indexes

Kwargs:
  • xyz_file (str) xyz file to write data to

write_xyz_str()

Write xyz file string

Buildingblock

class streamm.structures.buildingblock.Buildingblock(tag='blank', matrix=[100.0, 0.0, 0.0, 0.0, 100.0, 0.0, 0.0, 0.0, 100.0], unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: streamm.structures.structure.Structure

Data structure for describing a structure with particle that act as attachment points

Args:
  • tag (str): Identifier for structure

  • matrix (list): list of lattice vectors (v1,v2,v3) in order 1-3

  • with format: [v1(x),v1(y),v1(z),v2(x),v2(y),v2(z),v3(x),v3(y),v3(z)]

  • units_conf (dict): Dictionary of units for each attribute type

align_bond(key_i, key_j)

Align bond along the x-axis

                y
                ^
                |
                |
x <--- key_j - key_i - StrucC
Args:
  • key_i (int): particle index i

  • key_j (int): particle index j

align_yaxis(key_k, yangle)

Align position of particle k along the y-axis

                 y
                 ^
                 |      key_k (First non H neighbor of i)
                 |    /
x <---  R    - key_i
Args:
  • key_k (int): particle index

  • yangle (float) angle in radians

dump_pickle()

Write Pickle object

find_rsites()

Find dictionary of lists of particle indexes based on the rsites type

getSubStructure(pkeys, tag='blank')

This is redundant to getSubStructure in structures.py will be deprecated

get_rsite(rsite_i, n_i=0, Xn_i=0)

Get particle key of reactive site and the particle key of it’s Xn_i connected neighbor

Args:
  • rsite_i (str) Reactive site type

Kwargs:
  • n_i (int) index of reactive site within in list of

  • Xn_i (int) neighbor number of reactive site

Return:
  • Rkey - the particle to be replaced

  • XKey - the neighbor Xn_i of the particle to be replaced

prepattach(rsite_i, n_i=0, Xn_i=0, dir=1, yangle=0.0)

Prepare a building block to be attached to another

This is handy for batch attachments to not repeat the intial steps in the attach function

Args:
  • rsite_i (str): string identifier for reactive particle to be removed during join

  • n_i (int): nth reactive particle in list funcs[rsite_i]

  • Xn_i (int): nth bonded neighbor in bonded_nblist

  • dir (int): 1 to align along the positive x-axis, -1 to align along the negative x-axis

  • yangle (float): angle in radians

show_rsites()
Returns:
  • out_line (str): of all the rsites and the particles in them

Forcefields Module

Forcefield Components

class streamm.forcefields.particletype.Particletype(fftype1='X', unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Particle represented by a Force-field

Kwargs:
  • fftype1 (str): Forcefield key

  • units_conf (dict): Dictionary of units for each attribute type

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

class streamm.forcefields.bondtype.Bondtype(fftype1='blank', fftype2='blank', type='harmonic', unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Set of bond parameters

Kwargs:
  • fftype1 (str): Atom type

  • fftype2 (str): Atom type

  • type (str): Bond type

  • units_conf (dict): Dictionary of units for each attribute type

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

setharmonic(r0, kb)

set Harmonic parameters

Args:
  • r0 (float) distance

  • kb (float) force constant

\[E = kb( r - r_0 )^2 \]
class streamm.forcefields.angletype.Angletype(fftype1='blank', fftype2='blank', fftype3='blank', type='harmonic', unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Set of Angle parameters

Kwargs:
  • fftype1 (str): Atom type

  • fftype2 (str): Atom type

  • fftype3 (str): Atom type

  • type (str): Bond type

  • units_conf (dict): Dictionary of units for each attribute type

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

setharmonic(theta0, kb)

set Harmonic angle parameters

Args:
  • theta0 (float): angle

  • kb (float): force constant

\[E = kb( theta - theta_0 )^2\]
class streamm.forcefields.dihtype.Dihtype(fftype1='blank', fftype2='blank', fftype3='blank', fftype4='blank', type='multiharmonic', unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Set of Dihedral angle parameters

Args:
  • fftype1 (str) Atom type

  • fftype2 (str) Atom type

  • fftype3 (str) Atom type

  • fftype4 (str) Atom type

  • type (str) Bond type

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

setharmonic(mult, kb, theta_s)

set MultiHarmonic parameters dihedral_style charmm

Args:
  • mult (float)

  • kb (float) force constant kcal/mol

  • theta_s (float) angle degrees

gromacs

\[E = kb[ 1 - cos( mult*theta - theta_s ) ]\]

lammps

\[E = kb[ 1 - cos( n*theta - d ) ]\]
setopls(k1, k2, k3, k4)

set opls parameters

Args:
  • k1 (float) force constant kcal/mol

  • k2 (float) force constant kcal/mol

  • k3 (float) force constant kcal/mol

  • k4 (float) force constant kcal/mol

\[E = 1/2k1[1+cos(theta)]\]
\[+1/2k2[1-cos(2theta)]\]
\[+1/2k3[1+cos(3theta)]\]
\[+1/2k4[1-cos(4theta)]\]
setrb(C0, C1, C2, C3, C4, C5)

set Ryckaert-Bellemans parameters

Args:

C0 (float) force constant kcal/mol C1 (float) force constant kcal/mol C2 (float) force constant kcal/mol C3 (float) force constant kcal/mol C4 (float) force constant kcal/mol C5 (float) force constant kcal/mol

\[V_{rb}(theta) = sum_{n=0}^5 C_n [ cos(theta - 180 )^n ]\]
class streamm.forcefields.imptype.Imptype(fftype1='blank', fftype2='blank', fftype3='blank', fftype4='blank', type='improper', unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Set of improper dihedral angle parameters

Args:
  • fftype1 (str) Atom type

  • fftype2 (str) Atom type

  • fftype3 (str) Atom type

  • fftype4 (str) Atom type

  • type (str) Bond type

export_json()

Export object to json

Returns:
  • json_data (dict) json representation of the object

import_json(json_data)

Export object to json

Args:
  • json_data (dict) json representation of the object

setimp(e0, ke)

set Harmonic parameters

\[E = kb ( e_{lijk} - e_0 )^2 \]
Args:
  • e0 (float)

  • kb (float) force constant (energy)

Parameter Container

class streamm.forcefields.parameters.Parameters(tag='blank', unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Container for force-field parameters

Kwargs:
  • fftype1 (str): Forcefield key

  • units_conf (dict): Dictionary of units for each attribute type

add_angletype(angletype_i, deepcopy=True)

Add ‘Angletype’ object to angletypes dict in this container and update n_angletypes accordingly

add_bondtype(bondtype_i, deepcopy=True)

Add ‘Bondtype’ object to bondtypes dict in this container and update n_bondtypes accordingly

add_dihtype(dihtype_i, deepcopy=True)

Add ‘Dihtype’ object to dihtypes dict in this container and update n_dihtypes accordingly

add_imptype(imptype_i, deepcopy=True)

Add ‘Imptype’ object to imptypes dict in this container and update n_imptypes accordingly

add_particletype(particletype_i, deepcopy=True)

Add ‘Ljtype’ object to ljtypes dict in this container and update n_ljtypes accordingly

dump_pickle()

Pickle object

export_json(write_file=True)

Export particles to json

Kwargs:
  • write_file (boolean) to dump json to a file

Returns:
  • json_data (dict) json representation of the object

import_json(json_data={}, read_file=True)

Export object to json

Kwargs:
  • json_lattice (dict) json representation of the object

  • read_file (boolean) to read json from a file

update_units(new_unit_conf)

Update instance values with new units

Args:
  • new_unit_conf (dict): with unit type as the key and the new unit as the value

Calculations Module

Calculation

class streamm.calculations.calculation.Calculation(tag, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: pymatgen_core.core.units.ObjectUnits

Data structure for a calculation where input files are read in and output files and data files are produced.

These input, output and data files are tracked within a dictionary along with dictionaries of meta data and units.

Args:
  • tag (str): String identifier for object

Kwargs:
  • units_conf (dict): Dictionary of units for each attribute type

data(dict)

Calculation data

meta(dict)

Track Calculation data

files(dict)

Files needed and produced by calculation

files['input'] (dict)

Input files for calculation

files['templates'] (dict)

Templates files for calculation

files['scripts'] (dict)

Scripts files for calculation

files['output'] (dict)

Output files

files['data'] (dict)

Data produced by calculation

str['templates'] (dict)

Template files

add_file(file_type, file_key, file_name)

Add input file to simulation

add_paramC(paramC_i)

Add force field parameters based on fftypes in structure

add_refcalc(ref_calc)

Add reference calculation to current calculation this will copy the output of the reference calculation to the current calculation’s scratch location to be used by the current calculation

add_strucC(strucC_i)

Add a structure.Container to the simulation

analysis(output_key='log')

Read in results from streamm script

Args:

output_key (str): dictionary key for files[‘output’][output_key]

check(output_key='log')

Check if calculation has finished

compress_dirfiles(file_type, in_dirkey)

Compress files in directory

compress_files(file_type)

Compress files

cp_file(file_type, file_key, file_name, from_dirkey, to_dirkey)

Add file to calculation with add_file and copy the file to a directory

export_json(write_file=True)

Export particles to json

Kwargs:
  • write_file (boolean) to dump json to a file

Returns:
  • json_data (dict) json representation of the object

get_compress_str(file_type)

get bash string to compress files

get_cp_str(file_type, file_key, file_name, from_dirkey, to_dirkey)

Return bash command as string to copy a file

import_json(json_data={}, read_file=True)

Import object to json

Kwargs:
  • json_lattice (dict) json representation of the object

  • read_file (boolean) to read json from a file

load_str(file_type, file_key)

Read in a file as string and store in dictionary

Args:
  • file_type (str): dictionary key for files dictionary

  • file_key (str): dictionary key for files[file_type] dictionary

make_dir()

Check that needed directories exist

proc_log(log_file)

Read in new files created by script recorded in the log file.

Args:

log_file (str) script log file

pull(file_type_list=['output', 'data'])

Copy output and data of simulation from storage

push(file_type_list=['output', 'data'])

Push input files to resource

read_lines(file_name)

Read in file

replace_keys(input_str, input_dic)

Replace <key> in string with key value from dictionary

replace_prop(str_key)

Replace properties in string with values from properties dictionary

replacewrite_prop(str_key, file_type, file_key, file_name)

Replace properties in string and write to file

run()

Run calculation script

set_ffparam()

Create new parameter container to hold each unique type.

This is necessary for parameter outputs to no have redundant values.

set_resource(resource_i)

Set resource for simulation

set_strucC(strucC_i)

Add a structure.Container to the simulation

store(file_type_list=['input', 'scripts', 'output', 'data'])

Copy input, output and data of simulation to storage. This assumes storage is accessible by cp from ssh resource

update_units(new_unit_conf)

Update instance values with new units

Args:
  • new_unit_conf (dict): with unit type as the key and the new unit as the value

class streamm.calculations.calculation.MDrun(verbose=False)

Bases: object

Object to store the output of a single MD run

class streamm.calculations.calculation.ElectronTransfer(verbose=False)

Bases: object

Calculation of electron transfer between groups of particles

Gaussian

class streamm.calculations.gaussian.Gaussian(tag)

Bases: streamm.calculations.calculation.Calculation

Derived class implementing input/output methods Gaussian

analysis(output_key='log')

Read in results from gaussian

proc_fchk(fchk_file)

Read in structure information from gaussian fchk file

Args:
  • fchk_file (str) gaussian fchk file

proc_log(log_file)

Read data from Gaussian log file

NWChem

class streamm.calculations.nwchem.NWChem(tag, verbose=False)

Bases: streamm.calculations.calculation.Calculation

Derived class implementing input/output methods Gaussian

analysis(output_key='log')

Read in results from NWChem

load_json()

Load json file for reference

proc_log(log_file)

Read NWChem simulation log files

LAMMPS

class streamm.calculations.lammps.LAMMPS(tag)

Bases: streamm.calculations.calculation.Calculation

Derived class implementing input/output methods for LAMMPS

analysis(output_key='log', data2cply=True)

Read in results from LAMMPS

proc_in(in_file, data2cply=True)

Read in input parameters from lammps in file

Args:
  • in_file (str) lammps in file

proc_log(log_file, verbose=False, debug=False)

Read in results from lammps log file

Args:
  • log_file (str) lammps log file

read_data(data_file, btype='harmonic', atype='harmonic', dtype='multiharmonic', imptype='multiharmonic', debug=False)

Read Lammps data file

Args:
  • data_file (str) data file

read_data_pos(data_file, btype='harmonic', atype='harmonic', dtype='multiharmonic', imptype='improper', debug=False)

Read positions only from Lammps data file

Args:

data_file (str): data file data_file_path (str): data file path

read_param(param_file)

Read parameter file

Args:
  • param_file (str) parameter file

write_data(data_file='', data_file_path='./')

Write data file

Args:

data_file (str): name of the data file data_file_path (str): path where ‘data_file’ will be written

write_param(param_file, verbose=True, debug=False)

Write parameters to a file

Resource

class streamm.calculations.resource.Resource(tag='blank', home_dir='', res_type='local')

Bases: object

Data structure for a compute resource

Args:
  • tag (str) unique id for project

export_json(write_file=True)

Export particles to json

Kwargs:
  • write_file (boolean) to dump json to a file

Returns:
  • json_data (dict) json representation of the object

import_json(json_data={}, read_file=True)

Export object to json

Kwargs:
  • json_lattice (dict) json representation of the object

  • read_file (boolean) to read json from a file

make_dir()

Check that needed directories exist

set_home(home_dir)

Set the home/root directory of a resource

Project

class streamm.calculations.project.Project(tag, unit_conf={'amount': 'atom', 'angle': 'degree', 'capacitance': 'F', 'charge': 'e', 'conductance': 'S', 'current': 'A', 'density': 'amu_nm^3', 'electric_dipole_moment': 'D', 'emf': 'V', 'energy': 'Ha', 'force': 'GN', 'frequency': 'Hz', 'harm_bond_coeff': 'kCalmolsqang', 'intensity': 'cd', 'length': 'ang', 'magnetic_flux': 'Wb', 'mass': 'amu', 'memory': 'Kb', 'power': 'GW', 'pressure': 'KPa', 'resistance': 'ohm', 'temperature': 'K', 'time': 'ns', 'volume': 'nm^3'})

Bases: streamm.calculations.calculation.Calculation

Data structure for a project

Project is a set of calculations

Projects track:
  • file IO

  • simulations ran

  • computational resources used for each simulation

Data for each action is stored in a json file

Args:
  • tag (str): String identifier for object

Kwargs:
  • units_conf (dict): Dictionary of units for each attribute type

add_calc(calc_i, deepcopy=False)

Add Calculation to the project

Args:
  • calc_i (resource.Calculation): calculation object

Kwargs:
  • deepcopy (boolean): whether to make a deepcopy of the calculation

check()

Check if calculations in the project have finished

check_calcs()

Cycle through the dictionary of calculation objects and call their check methods in the ‘appropriate’ order. In the future this will be expanded to cycle through a DAG ‘list’ of jobs to run

export_json(write_file=True)

Export particles to json

Kwargs:
  • write_file (boolean) to dump json to a file

Returns:
  • json_data (dict) json representation of the object

import_json(json_data={}, read_file=True)

Export object to json

Kwargs:
  • json_lattice (dict) json representation of the object

  • read_file (boolean) to read json from a file

make_dir()

Run calculations in the project

pull()

Run calculations in the project

push_calcs()

Cycle through the dictionary of calculation objects and call their push methods in the ‘appropriate’ order. In the future this will be expanded to cycle through a DAG ‘list’ of jobs to run

run()

Run calculations in the project

run_calcs()

Cycle through the dictionary of calculation objects and call their run methods in the ‘appropriate’ order. In the future this will be expanded to cycle through a DAG ‘list’ of jobs to run

set_resource(resource_i)

Set resource for simulation

store()

Store calculations in the project

update_units(new_unit_conf)

Update instance values with new units

Args:
  • new_unit_conf (dict): with unit type as the key and the new unit as the value

MPI Module

class streamm.mpi.mpiBase.MsgrBoost(commObj)

Bases: streamm.mpi.mpiBase.ParallelMsgr

Derived class implementing interface in the base class using Boost MPI libraries

allReduceSum(data)

Add data elements in localData across processors and put on all world procs

barrier()

Barrier for world comm

bcast(data, root=0)

Broadcast from root proc to world comm

gatherList(data, root=0)

Gather data in list from world comm on root proc and return as a continuous list

reduceSum(data, root=0)

Add data elements in localData across processors and put result on root proc

class streamm.mpi.mpiBase.MsgrMpi4py(commObj)

Bases: streamm.mpi.mpiBase.ParallelMsgr

Derived class implementing interface in the base class using Mpi4py libraries

allReduceSum(localData)

Add data elements in localData across processors and put on all world procs

barrier()

Barrier to world comm

bcast(localData, root=0)

Broadcast to world communicator

gatherList(localData, root=0)

Gather data in list from world comm on root proc and return as a continuous list

reduceSum(localData, root=0)

Add data elements in localData across processors and put result on root proc

class streamm.mpi.mpiBase.MsgrSerial

Bases: streamm.mpi.mpiBase.ParallelMsgr

Derived class implementing interface in the base class using no MPI (serial) libraries

allReduceSum(data)

Add data elements in localData across processors and put on all world procs

barrier()

Barrier for world comm

bcast(data, root=0)

Broadcast from root proc to world comm

gatherList(data, root=0)

Gather data in list from world comm on root proc and return as a continuous list

reduceSum(data, root=0)

Add data elements in localData across processors and put result on root proc

class streamm.mpi.mpiBase.ParallelMsgr(rk, sz)

Bases: object

Base class defining the interface to parallel communication methods

allReduceSum(data)

Must be implemented in derived

barrier()

Must be implemented in derived

gatherList(data, root=0)

Must be implemented in derived

getCommSize()

Number of processors in world communicator

getRank()

ID of current processor

Returns:

integer rank of current processor

reduceSum(data, root=0)

Must be implemented in derived

splitListOnProcs(data)

Split up global input list equally (as possible) and return the ‘chunk’ of list belonging to each processor. Note, no communication is performed, input data is known globally.

Split algorithm will guarantee returning a list that has ‘rank’ number of elements. Not all local lists will in general be the same length.

NOTE: If len(data) > rank some of the elements of the split list will be of zero length, so the local list on some processors can be empty. Calling program should account for this.

Args:

data: list of data [..]

Returns:

list of data for this local processor

tupleOfLists2List(tup)

Take a tuple of lists and convert to single list eg ([a,b],[c,d],[e,f],…) –> [a,b,c,d,e,f]

streamm.mpi.mpiBase.getMPIObject()

Driver for comm classes. Selects MPI-comm module if found and builds appropriate derived class

Returns: an mpi object of the appropriate derived class

streamm.mpi.mpiBase.getMPISerialObject()

Driver for comm classes. Forces serial MPI-comm module

Returns: an mpi serial object

util Module

class streamm.util.replicate.Replication(name_i, name_j, name_ij, method, n)

Bases: object

Object to record the replication of structure

streamm.util.replicate.add_struc(strucC_i, other, n_i, seed, p=None, tag='blank')

Add structure other to strucC_i n times via random placement

streamm.util.replicate.add_struc_grid(strucC_i, other, n_i, p=None, tag='blank', calc_overlap=True)

Add structure other to strucC_i n times on a grid

Args:

n_i (int) number of times to replicate