This module provides builders used to generate the initial atomic
configuration (pdb) that a fullrmc Engine will
optimize. It covers amorphous systems and nanoparticles built by randomly
inserting and orienting molecular building blocks, crystal supercells and
nanoparticles built from a unitcell, atoms element transmutation and
multi-domain (e.g. core-shell, substrate-supported) systems combining
several of the above builders together.
random() -> x in the interval [0, 1).
Normalize a value into a validated (lower, upper) bounds tuple.
objName (str): name of the calling object’s class, used to build descriptive assertion error messages
bndName (str): name of the bounds family being validated
(e.g. 'ellipsoid', 'supercell'), used in error messages
varName (str): name of the specific variable being validated
(e.g. 'a', 'b'), used in error messages
val (number, list, tuple): the value to normalize. If a single
number is given, it is used as both the lower and upper bound.
If a list or tuple, it must contain exactly the
(lower, upper) bound values
isInt (boolean): whether the bounds must be integers rather than floats
minv (None, number): if given, the lower bound must be >= minv
maxv (None, number): if given, the lower bound must be <= maxv
canbeEqual (boolean): whether the upper bound is allowed to be exactly equal to the lower bound
bounds (tuple): the validated (lower, upper) bounds tuple, cast
to INT_TYPE if isInt is True or FLOAT_TYPE otherwise
Normalize and validate a single ellipsoid semi-axis dimension bounds value, enforcing a minimum length of 1 angstrom.
obj (object): the calling builder instance, used only to read its class name for descriptive assertion error messages
vn (str): name of the ellipsoid dimension being validated
(e.g. 'a', 'b' or 'c'), used in error messages
val (number, list, tuple): the dimension bounds value. If a
single number is given, it is used as both the lower and upper
bound. If a list or tuple, it must contain exactly the
(lower, upper) bound values
bounds (tuple): the validated (lower, upper) FLOAT_TYPE bounds tuple
Randomly draw the three semi-axes lengths of an ellipsoid within given bounds for each axis.
obj (object): the calling builder instance, used only to read its class name for descriptive assertion error messages
a (number, list, tuple): semi-axis ‘a’ bounds, in the same
format accepted by get_bounds()
b (number, list, tuple): semi-axis ‘b’ bounds, in the same
format accepted by get_bounds()
c (number, list, tuple): semi-axis ‘c’ bounds, in the same
format accepted by get_bounds()
dimensions (tuple): a tuple of the three randomly drawn
(a, b, c) semi-axes lengths
bounds (tuple): a tuple of the three validated
(aBounds, bBounds, cBounds) bounds tuples the dimensions
were drawn from
Randomly draw the three integer supercell repetitions along a, b and c within given bounds for each axis.
obj (object): the calling builder instance, used only to read its class name for descriptive assertion error messages
a (integer, list, tuple): supercell repetition along ‘a’
bounds, in the same format accepted by get_bounds()
b (integer, list, tuple): supercell repetition along ‘b’
bounds, in the same format accepted by get_bounds()
c (integer, list, tuple): supercell repetition along ‘c’
bounds, in the same format accepted by get_bounds()
supercell (tuple): a tuple of the three randomly drawn
(a, b, c) integer repetitions
bounds (tuple): a tuple of the three validated
(aBounds, bBounds, cBounds) bounds tuples the repetitions
were drawn from
Validate and normalize a 3D vector into a unit orientation vector.
obj (object): the calling builder instance, used only to read its class name for descriptive assertion error messages
vector (list, tuple, numpy.ndarray): the 3 items non-zero vector to normalize
vector (numpy.ndarray): the normalized unit vector
Bases: object
Base Builder for all builder implemenations. It must not be instanciated
structs (pdbparser.pdbparser, list): list of primary structures (e.g. molecules) to use upon building the atomic configuration
boundaryConditions (PeriodicBoundaries, numpy.ndarray, number): The configuration’s boundary conditions. If numpy.ndarray is given, it must be pass-able to a PeriodicBoundaries instance. Normally any real numpy.ndarray of shape (1,), (3,1), (9,1), (3,3) is allowed. If number is given, it’s like a numpy.ndarray of shape (1,), it is assumed as a cubic box of box length equal to number.
bonds (None, dict): dictionary of defined atom pairs bonds that will be used upon building structure to prevent elements pair distance below bonds threshold
stoichiometry (None, list): stoichriometry ratios between the different given primary structures. If None, then all structures stoichriometry will be the same
density (number): configuration desired density in g/cm^3. e.g. for a pure water system at room temperature and under normal pressure conditions, density must be equal to 0.997. If None is given, the density will be automatically set to 0.997
restrictions (None, string, list): list of geometric restrictions to be applied when creating the system. e.g. ‘(x**2 + y**2 + z**2)**0.5 <=10’ can be used to prevent any atom to be place in a sphere centered around 0 and of radius 10 angstrom
Set the builder’s name, used to name the built pdb structure.
name (string): the builder’s name
Set building blocks primary structures
pdbs (pdbparser.pdbparser, list): list of primary structures (e.g. molecules) to use upon building the atomic configuration
bonds (None, dict): dictionary of defined atom pairs bonds that will be used upon building structure to prevent elements pair distance below bonds threshold
Set bonds matrix
bonds (None, dict): dictionary of defined atom pairs bonds that will be used upon building structure to prevent elements pair distance below bonds threshold
_fudgeFactor (number): internal flag. Fraction of the sum of
the two elements’ covalent radii used as the default bond
cutoff distance for any element pair not explicitly given
in bonds
Set the building blocks stoichiometry ratios
stoichiometry (None, list): stoichriometry ratios between the different given primary structures. If None, then all structures stoichriometry will be the same
inWeight (bool): whether to set stoichiometry in pdbs weight or in insertion number
Set the final structure desired boundary conditions
boundaryConditions (PeriodicBoundaries, numpy.ndarray, number): The configuration’s boundary conditions. If numpy.ndarray is given, it must be pass-able to a PeriodicBoundaries instance. Normally any real numpy.ndarray of shape (1,), (3,1), (9,1), (3,3) is allowed. If number is given, it’s like a numpy.ndarray of shape (1,), it is assumed as a cubic box of box length equal to number.
Set the final structure density in g/cm^3
density (number): configuration desired density in g/cm^3. e.g. for a pure water system at room temperature and under normal pressure conditions, density must be equal to 0.997. If None is given, the density will be automatically set to 0.997
Set the insertion parameter. This is another way to force the number of insertions per given primary structure. This will automatically reset the density of the system
insertionNumber (list): list of integers
Set the geometric restrictions
restrictions (None, string, list): list of geometric restrictions to be applied when creating the system. e.g. ‘(x**2 + y**2 + z**2)**0.5 <=10’ can be used to prevent any atom to be place in a sphere centered around 0 and of radius 10 angstrom
Set existing prior structure
pdb (None, pdbparser.pdbparser): Set a prior structure that is considered present at time 0. If None, any previously set prior structure is cleared
name (None, str): the prior structure’s name. If None, the
given pdb’s own name is used instead
Build configuration
Get a pdbparser instance of the built structure
pdb (pdbparser.pdbparser): the built structure
Bases: BaseAmorphousBuilder
Create amorphous system using random translations and rotations
Build the amorphous system
order (bool, list): order of insertion. If True, insertion will start with the biggest pdb building block to the smallest. If False, shuffled order of insertion will be used. If list, it must be a list of building blocks indexes
maxAttempts (integer): the maximum number of attempts to insert a specific pdb building block before moving to the next one.
_reset (boolean): internal flag. If True, or if the builder was never built before, all build attributes are reset before starting a fresh insertion
_logInc (integer): internal flag. Percent complete increment step at which a progress message is logged, between 0 and 100
_log (boolean): internal flag. Whether to log progress and completion messages
_debug (boolean): internal flag. If True, log a debug message whenever an accepted insertion violates the minimum bond distance with already inserted atoms
_interceptHook (None, object): internal flag. Optional hook
instance polled for a 'stop_builder' message between
insertions, allowing the build to be interrupted gracefully
builtIntercepted (None, boolean): True if the build was
interrupted early via _interceptHook, False if it ran
to completion, or None if there was nothing left to insert
Bases: AmorphousSystem
Create an isolated amorphous nanoparticle shaped as an ellipsoid, by randomly inserting and orienting building blocks within an ellipsoid of semi-axes a, b and c rather than throughout the whole periodic simulation box.
a (number, list, tuple): ellipsoid semi-axis ‘a’ length bounds
in angstrom, must be >=1. If a single number is given, it is
used as both the lower and upper bound. If a list or tuple, it
must contain the (lower, upper) bound values, and the
actual length is drawn randomly within them
b (number, list, tuple): ellipsoid semi-axis ‘b’ length bounds,
same format as a
c (number, list, tuple): ellipsoid semi-axis ‘c’ length bounds,
same format as a
*args, **kwargs: other arguments and keyword arguments
forwarded to BaseAmorphousBuilder. boundaryConditions
must not be given, it is automatically computed from the
ellipsoid dimensions
Set building blocks primary structures. Same as
BaseAmorphousBuilder.set_pdbs(), additionally resetting all
building blocks ellipsoid penetration ratios to their default
value of 1 via set_penetration().
*args, **kwargs: arguments and keyword arguments
forwarded to BaseAmorphousBuilder.set_pdbs()
result (None): always None, forwarded from
BaseAmorphousBuilder.set_pdbs() which doesn’t
return a value
Set how deeply each building block is allowed to penetrate through the ellipsoid surface upon insertion.
penetration (None, list): list of penetration ratios, one
per building block pdb, in the same order as given to
set_pdbs(). Each ratio must be >0 and <=1, where 1
means the building block must be fully contained inside
the ellipsoid and smaller values allow it to stick out
further past the ellipsoid surface. If None, all building
blocks are set to a penetration ratio of 1
Build the amorphous nanoparticle. Same as AmorphousSystem.build(),
additionally clearing the built pdb’s boundary conditions (the
nanoparticle is isolated, not periodic) and recomputing its
number density and density from the ellipsoid volume rather than
the periodic box volume.
*args, **kwargs: arguments and keyword arguments
forwarded to AmorphousSystem.build()
builtIntercepted (None, boolean): same as
AmorphousSystem.build()’s return value
Automatically compute and set the periodic boundary conditions
big enough to contain the ellipsoid plus a padding margin large
enough to fit the biggest building block, and set the ellipsoid’s
volume accordingly. Unlike
BaseAmorphousBuilder.set_boundary_conditions(), this method
takes no boundary conditions argument since it is entirely
derived from the ellipsoid semi-axes lengths a, b and
c
Bases: object
Base builder for all crystal-based builder implementations built from one or more unitcells. It must not be instanciated directly.
structs (CrystalMaker, dict, str, list): the primary crystal
unitcell structure(s) to build from. Each item can be a
pdbparser.Utilities.Crystallography.CrystalMaker
instance, a dictionary of keyword arguments used to
instanciate one, or a string cif file path
supercell (None, int, list, tuple): unused by this base class, kept for subclasses convenience
name (string): the builder’s name
*args, **kwargs: unused, accepted for subclasses convenience
Set the builder’s name, used to name the built pdb structure.
name (string): the builder’s name
Set building blocks primary structures
cifs (pdbparser.Utilities.Crystallography.CrystalMaker, list): list of primary structures (e.g. unitcells) to use upon building the atomic configuration
Bases: BaseCrystalBuilder
Build a periodic crystal supercell structure by repeating a single unitcell along its a, b and c basis vectors.
structs (CrystalMaker, dict, str): a single primary crystal
unitcell structure, in any format accepted by
BaseCrystalBuilder.set_cifs()
supercell (int, list, tuple): number of unitcell repetitions
bounds along a, b and c. If a single number is given, it is
used as both the lower and upper bound for all three
directions. If a list or tuple of 3 items, each item is either
a number or a (lower, upper) bounds pair for the
corresponding direction, and the actual repetition count is
drawn randomly within them
*args, **kwargs: other arguments and keyword arguments
forwarded to BaseCrystalBuilder
The built structure’s boundary conditions, or None if the structure hasn’t been built yet.
Set the supercell repetitions along a, b and c, drawing the actual repetition counts randomly within given bounds. Setting this after a structure was already built clears the built structure if the drawn supercell changes.
supercell (int, list, tuple): number of unitcell repetitions bounds along a, b and c, in the same format accepted by this class’s constructor
Build the crystal supercell structure.
supercell (None, int, list, tuple): if given, forwarded to
set_supercell() to redraw the supercell repetitions
before building. If None, the previously set supercell is
used
_debug (boolean): internal flag, currently unused, kept for interface consistency with other builders
_log (boolean): internal flag. Whether to log start and completion messages
_interceptHook (None, object): internal flag, cleared before building. Kept for interface consistency with other builders; supercell creation itself cannot be interrupted mid-way
builtIntercepted (boolean): always False, kept for
interface consistency with other builders’ build()
Get a pdbparser instance of the built structure
pdb (pdbparser.pdbparser): the built structure
Bases: BaseCrystalBuilder
Build an isolated crystal nanoparticle shaped as an ellipsoid, by generating a large enough crystal supercell from a single unitcell, orienting it and keeping only the atoms (or unitcells) falling inside the ellipsoid of semi-axes a, b and c.
a (number, list, tuple): ellipsoid semi-axis ‘a’ length bounds
in angstrom, must be >=1. If a single number is given, it is
used as both the lower and upper bound. If a list or tuple, it
must contain the (lower, upper) bound values, and the
actual length is drawn randomly within them
b (number, list, tuple): ellipsoid semi-axis ‘b’ length bounds,
same format as a
c (number, list, tuple): ellipsoid semi-axis ‘c’ length bounds,
same format as a
orientation (None, list): forwarded to set_orientation()
*args, **kwargs: other arguments and keyword arguments
forwarded to BaseCrystalBuilder
Set the nanoparticle’s crystallographic orientation, used to rotate the supercell before cutting out the ellipsoid so that a chosen crystal direction aligns with the x-axis, and rotate the final ellipsoid-cut nanoparticle back to its original orientation.
orientation (None, list, tuple, numpy.ndarray): the 3
items non-zero orientation vector. If None, defaults to
(1,0,0) i.e. no rotation
Build the crystal nanoparticle.
strategy (str): how atoms falling outside the ellipsoid
are handled once the oversized supercell is generated.
'atomic' keeps only the individual atoms found inside
the ellipsoid regardless of their unitcell. 'keep unitcell'
keeps every atom belonging to a unitcell that has at least
one atom inside the ellipsoid. 'remove unitcell'
removes every atom belonging to a unitcell that has at
least one atom outside the ellipsoid
_debug (boolean): internal flag, currently unused, kept for interface consistency with other builders
_log (boolean): internal flag. Whether to log start and completion messages
_interceptHook (None, object): internal flag, cleared before building. Kept for interface consistency with other builders; the ellipsoid cut itself cannot be interrupted mid-way
builtIntercepted (boolean): always False, kept for
interface consistency with other builders’ build()
Get a pdbparser instance of the built structure
pdb (pdbparser.pdbparser): the built structure
Bases: object
Build a new structure from an existing one by randomly transmuting a fraction of its atoms from one element (or atom name) to another, e.g. to simulate isotopic substitution or doping.
structs (CrystalMaker, pdbparser.pdbparser): the existing structure to transmute atoms from. If a CrystalMaker instance is given, it is first converted to a pdbparser instance (generating a (1,1,1) supercell if needed)
name (string): the builder’s name
*args, **kwargs: unused, accepted for interface consistency with the other builders
The original (pre-transmutation) structure’s boundary conditions.
Set the builder’s name, used to name the built pdb structure.
name (string): the builder’s name
Build the transmuted structure by copying the original structure and randomly transmuting a fraction of its atoms according to the given transmutation rules.
transmutations (dict): the transmutation rules. It can
either be a flat dict mapping an element symbol to a
(newElement, newAtomName, ratio) tuple (shorthand for
{'elements': ...}), or a dict with up to two keys:
'elements' mapping an element symbol to a
(newElement, newAtomName, ratio) tuple applied to every
atom of that element, and 'names' mapping a specific
atom name to a (newElement, newAtomName, ratio) tuple
applied only to atoms with that exact name (checked before
and taking precedence over the 'elements' rule).
ratio must be between 0 and 1 and is the per-atom
probability of actually transmuting that atom
_log (boolean): internal flag. Whether to log start and completion messages
_interceptHook (None, object): internal flag, cleared before building. Kept for interface consistency with other builders; the transmutation loop itself cannot be interrupted mid-way
builtIntercepted (boolean): always False, kept for
interface consistency with other builders’ build()
Get a pdbparser instance of the built structure
pdb (pdbparser.pdbparser): the built structure
Bases: object
Build a multi-domain system by inserting several independently built domains (e.g. isolated nanoparticles, amorphous chunks, transmuted structures) next to and possibly intersecting each other, optionally around a fixed substrate domain. This allows building complex systems such as core-shell nanoparticles, substrate-supported nanoparticles or heterogeneous multi-phase assemblies, using any combination of the other builders in this module as sub-builders for each domain.
domains (list): list of domain definition dictionaries. Each dictionary can have the following keys:
'name' (str): the domain’s name, defaults to
'domain %i'%idx. Automatically de-duplicated if reused
'structure' (str, list, pdbparser.pdbparser, CrystalMaker):
the domain’s structure, either given directly as a pdb or
cif file path, a list of pdb file lines, a pdbparser
instance or a CrystalMaker instance, or used as the
structs argument of 'builder' when one is given
'domain_molecules_name' (None, str): optional molecules
name override, maximum 3 characters
'single_atoms' (bool): whether the domain is inserted
atom by atom rather than as a whole rigid block. Defaults to
False
'intersection_likelihood' (number): probability >=0
that this domain is allowed to intersect with previously
inserted domains rather than being rejected. Defaults to 0
'number_of_insertions' (int): number of times this
domain is inserted. Defaults to 1
'fresh_build_per_insertion' (bool): whether the domain’s
sub-builder is rebuilt from scratch (new random
conformation) at every insertion, or built once and reused.
Defaults to True
'insert_all_or_none' (bool): whether the whole domain
insertion must be rejected if any of its atoms can’t be
placed. Defaults to False
'allow_replacement' (bool): whether later domains are
allowed to intersect and replace this domain’s atoms.
Defaults to True
'randomly_rotate' (bool): whether to randomly rotate the
domain upon insertion. Defaults to True
'randomly_translate' (bool): whether to randomly
translate the domain upon insertion. Defaults to True
'fixed_position' (None, ‘center’, list): force the
domain’s position instead of randomly translating it
'fixed_orientation' (None, list): force the domain’s
orientation instead of randomly rotating it
'builder' (None, str, class): optional sub-builder class
(or its name) among CrystalNanoparticle,
AmorphousNanoparticle, AmorphousSystem,
CrystalSupercell and AtomsTransmutator,
used to generate the domain’s structure from 'structure'
'builder_kwargs' (dict): keyword arguments forwarded to
the sub-builder’s constructor when 'builder' is given
'build_kwargs' (dict): keyword arguments forwarded to
the sub-builder’s build() method when 'builder' is
given
'substrate' (bool): marks this domain as the fixed
substrate. At most one domain may be a substrate. When set,
'number_of_insertions' is forced to 1 and
'randomly_translate', 'randomly_rotate',
'fixed_position' and 'fixed_orientation' are forced
to their neutral values, since the substrate defines the
system’s boundary conditions itself
boundaryConditions (None, PeriodicBoundaries, numpy.ndarray,
number): the configuration’s boundary conditions, in the same
format accepted by
BaseAmorphousBuilder.set_boundary_conditions(). Must not
be given when one of the domains is a substrate, since the
substrate’s own boundary conditions are used instead
bonds (None, dict): dictionary of defined atom pairs bonds that will be used upon building structure to prevent elements pair distance below bonds threshold
name (string): the builder’s name
_mappingUnit (number): internal flag. Approximate real-space size in angstrom of one cell of the internal insertion map grid used to speed up overlap detection
Set the builder’s name, used to name the built pdb structure.
name (string): the builder’s name
Set the final structure desired boundary conditions
boundaryConditions (PeriodicBoundaries, numpy.ndarray, number): The configuration’s boundary conditions. If numpy.ndarray is given, it must be pass-able to a PeriodicBoundaries instance. Normally any real numpy.ndarray of shape (1,), (3,1), (9,1), (3,3) is allowed. If number is given, it’s like a numpy.ndarray of shape (1,), it is assumed as a cubic box of box length equal to number.
_check (boolean): internal flag, currently unused (checks are commented out), kept for interface consistency
Set bonds matrix
bonds (None, number, dict): dictionary of defined atom pairs bonds that will be used upon building structure to prevent elements pair distance below bonds threshold. If a number is given, it is used as the bond cutoff distance for every element pair
_fudgeFactor (None, number): internal flag. If given,
updates the fraction of the sum of the two elements’
covalent radii used as the default bond cutoff distance
for any element pair not explicitly given in bonds
Build domains system.
order (bool, list): order of insertion. If True, insertion will start with the biggest pdb building block to the smallest. If False, shuffled order of insertion will be used. If list, it must be a list of building blocks indexes
failAll (bool): whether to fail the build if any of the given domains failed to be built. Failing to build the substrate will always result in failing the whole build
_maxNumberOfIntersections (integer): internal flag. Initial
size of the per-atom buffer used to track how many
already-built atoms a newly inserted domain’s atoms
intersect with. Automatically grown by increments of 8 up
to _flexibleLimit if this initial size is exceeded
_flexibleLimit (integer): internal flag. Hard upper limit on the automatic growth of the intersections buffer described above. If reached without finding a valid (non-overflowing) intersection count, the domain’s atoms are all rejected
_debug (boolean): internal flag, currently unused, kept for interface consistency with other builders
_log (boolean): internal flag. Whether to log progress and completion messages
_interceptHook (None, object): internal flag. Optional hook
instance polled for a 'stop_builder' message between
domain insertions, allowing the build to be interrupted
gracefully
builtIntercepted (boolean): True if the build was
interrupted early via _interceptHook, False if it ran
to completion
Get a pdbparser instance of the built structure
pdb (pdbparser.pdbparser): the built structure