Configuration¶
-
class
Configuration
¶ A configuration contains both the particles and the spatial domain/boundaries.
For the particles, this includes both the pool of particles which may exist (referred to as particle types) in addition to the particles which physically exist (referred to as particles).
Before particles are physically added to the system, all particle types which may exist must be defined. Once particles are added to the system, new particle types cannot be added. Similarly, site and bond types are also defined at the same time as particle types and are referred to as unique types. Unique types are stored in essentially the same fashion as particle types, except they have been stripped of their non-unique sites and bonds. Two different particles cannot share a site type.
Groups of different particle/site types and other metrics may be defined. These groups then define a selection which can be used to distinguish subsets of the configuration (e.g., types of particles). This selection may be further reduced to single particles. These selections are then used to modify a subset of the configuration (e.g., removal and displacement) of a selection of particles/sites.
The spatial domain contains periodic boundaries and cells.
Finally, note that an optimization for grand canonical ensemble simulations allows for the possibility of ghost particles. Ghost particles do not interact and serve as a pool for adding/removing particles in an optimized fashion without having to resize the particle arrays. Thus, one must use caution when accessing particles and sites by indices, because these indices may include ghost particles.
Construction
-
Configuration
(const argtype &args = argtype())¶ args:
particle_type[i]: add the i-th type of particle to the configuration. The “[i]” is to be substituted for an integer 0, 1, 2, … If only one particle type, the “[i]” is optional.
wrap: wrap particle centers within domain (default: true).
physical_constants: optional class_name of PhysicalConstants.
set_cutoff_min_to_sigma: if true and cutoff < sigma, cutoff = sigma (default: false). This is typically used for HardSphere models that didn’t specify cutoff.
Same as above, but also set the domain.
Typing
Types of sites and particles.
-
void
add_particle_type
(const std::string file_name, const std::string append = "")¶ Add a particle type that may exist by LMP file (see FileLMP).
- Parameters
append
: optionally append to name to use same file but keep unique names.
-
int
num_particle_types
() const¶ Return the number of particle types.
-
int
num_site_types
() const¶ Return the number of site types.
-
int
num_bond_types
() const¶ Return the number of bond types.
-
int
num_angle_types
() const¶ Return the number of angle types.
-
std::string
type_to_file_name
(const int type) const¶ Return the file name used to initialize the particle types.
-
const ParticleFactory &
particle_types
() const¶ Return the particle types.
Add a custom type of model parameter. Name it the same as an atom property before reading file to make a custom ModelParam.
-
const ModelParams &
model_params
() const¶ Return the model parameters (e.g., sigma, epsilon, etc).
-
void
set_model_param
(const char *name, const int site_type, const double value)¶ Modify model parameter of a given site type and name to value.
-
void
set_model_param
(const char *name, const int site_type1, const int site_type2, const double value)¶ Modify a mixed model parameter of given site types and name to value.
-
void
add_model_param
(const std::string name, const double value)¶ Add model parameter of a given name to value.
-
void
add_or_set_model_param
(const std::string name, const double value)¶ Add or set model parameter of a given name to value.
Set the physical constants.
-
const PhysicalConstants &
physical_constants
() const¶ Return the physical constants.
-
const ParticleFactory &
unique_types
() const¶ Return the unique types. Only unique sites and bonds are included. Thus, the site index is the same as the numeric value for the site type. And the same for bonds. This serves as a container for properties based on site or bond type.
-
int
max_sites_in_any_particle
() const¶ Return the maximum number of sites in any particle type.
-
void
set_site_type
(const int particle_type, const int site, const int site_type)¶ Change the site type of a given site in all particles of given type.
Groups
Groups of sites and particles
Add a group (after types are defined but before particles are added).
- Parameters
name
: Optionally provide a name. If no name is provided, the name is assigned to be the numerical indices of the order of groups added.
-
int
num_groups
() const¶ Return the number of group selections.
-
int
particle_type_to_group
(const int particle_type) const¶ Return the index of the group based on particle types. If the group does not exist, return -1.
-
int
particle_type_to_group_create
(const int particle_type)¶ Same as above, except create the group if it does not already exist.
Particles
Physically existing sites and particles
-
void
add_particle_of_type
(const int type)¶ Add a particle of a given type.
-
const Particle &
particle
(const int index) const¶ Return particle by index. Note this index is contiguous from values 0 to num_particles -1, unlike the selection indices (due to ghost particles). Note that this method can be slow because the particle index filters out ghost particles.
-
Particle
particle
(const int index, const int group) const¶ - Parameters
group
: Provide a group index to consider only a subset of the configuration.
Same as above, but filter the particle by the group index. Returns a copy of the filtered particle, instead of a constant reference. Note: this method can be prone to errors if used to define a constant reference to, for example, site or position in particle.
-
const Select &
selection_of_all
() const¶ Return selection of all particles and sites in the configuration. This selection does not include ghost particles.
-
int
num_particles
(const int group = 0) const¶ Return the number of particles.
- Parameters
group
: Provide a group index to consider only a subset of the configuration. By default, a value of zero is for the entire configuration.
-
int
num_sites
(const int group = 0) const¶ Return the number of sites.
- Parameters
group
: Provide a group index as described above.
-
int
num_particles_of_type
(const int type) const¶ Return the number of particles of a given particle type. If type == -1, return number of particles of all types.
-
std::vector<int>
num_sites_of_type
(const Select &selection) const¶ Return the number of sites of each type in selection.
-
void
num_sites_of_type
(const Select &selection, std::vector<int> *num) const¶ Same as above, but optimized to use existing data structure.
-
std::vector<int>
num_sites_of_type
(const int group_index = 0.) const¶ Return the number of sites of each type in group.
-
void
num_sites_of_type
(const int group_index, std::vector<int> *num) const¶ Same as above, but optimized to use existing data structure.
Modifications
Modifications to a configuration (e.g., moving, adding or deleting particles/sites. A subset of the configuration is defined by a Select.
-
void
update_positions
(const std::vector<std::vector<double>> coords)¶ Load coordinates by per-site vector containing per-dimension vector. Requires coordinates for all sites and dimensions.
-
void
update_positions
(const Select &select, const bool no_wrap = false, const bool no_exclude = false)¶ Update the positions and properties from a selection.
- Parameters
no_wrap
: If true, do not wrap. If false, defer to default behavior.no_exclude
: If true, do not exclude properties.
-
void
copy_particles
(const Configuration &config, const bool add_missing = false)¶ - Parameters
add_missing
: Add missing particles of the same type.
Copy the existing particles in a given config by replacing positions. Types must match config in the same order.
-
void
displace_particles
(const Select &selection, const Position &displacement)¶ Displace selected particle(s). No periodic boundary conditions applied.
-
void
displace_particle
(const Select &selection, const Position &displacement)¶ Same as above except for only one particle that is selected.
-
void
displace
(const Select &selection, const Position &displacement)¶ Displace the selection. No periodic boundary conditions applied.
-
void
replace_position
(const Select &select, const Particle &replacement)¶ Replace positions of particle by selection.
-
void
remove_particle
(const Select &selection)¶ Same as above except for only one particle that is selected.
-
void
recenter_particle_positions
(const int group_index = 0)¶ Set the particle positions of the group to the geometric center of the site positions.
Domain
A configuration’s domain includes periodic boundaries and cells.
Set the domain.
-
int
dimension
() const¶ Return the dimensionality of space.
-
void
init_wrap
(const bool wrap = true)¶ Set whether or not to wrap particles.
Ghosts
Functions which require knowledge of ghost particles and thus not for typical users.
-
void
revive
(const Select &selection)¶ Revive the particles in the selection previously removed (ghosts).
-
const ParticleFactory &
particles
() const¶ Return the particles. Warning: typically not for users because it may include ghost particles.
-
const Particle &
select_particle
(const int index) const¶ Return particle by index provided in selection. Warning: typically not for users because it may include ghost particles.
-
int
newest_particle_index
() const¶ Return the selection-based index (includes ghosts) of the last particle added.
-
void
wrap_particle
(const int particle_index)¶ Wrap particle position. The index may include ghost particles.
-
void
add_non_ghost_particle_of_type
(const int type)¶ Add a particle of a given type without using ghosts.
Sites
Modify properties of sites directly. Note that indices include ghosts.
-
void
set_selection_physical
(const Select &select, const bool phys)¶ Set selection as physical/nonphysical.
-
void
set_property
(const std::string name, const double value, const int particle_index)¶ Set particle property.
-
void
add_site_property
(const std::string name, const double value, const int particle_index, const int site_index)¶ Add the property to a site in a particle.
-
void
add_or_set_site_property
(const std::string name, const double value, const int particle_index, const int site_index)¶ Add or set the property of a site in a particle.
-
void
add_or_set_particle_type_site_property
(const std::string name, const double value, const int particle_type, const int site_index)¶ Add or set the property of a site in a particle type.
-
void
set_site_property
(const std::string name, const double value, const int particle_index, const int site_index)¶ Set the property of a site in a particle by name.
-
void
set_site_property
(const int index, const double value, const int particle_index, const int site_index)¶ Set the property of a site in a particle by index.
-
void
add_excluded_property
(const std::string name)¶ Add an property excluded from Configuration::update_positions()
Checks
Consistency checks and tests.
-
bool
are_all_sites_physical
() const¶ Return true if all sites are physical.
-
bool
is_equal
(const Configuration &configuration, const double tolerance) const¶ Check if configuration is approximately equivalent. Not all quantities are checked, including ghosts, etc.
-
std::string
status_header
() const¶ Return the header of the status for periodic output.
-
std::string
status
() const¶ Return the brief status for periodic output.
-
void
serialize
(std::ostream &ostr) const¶ Serialize.
-
Configuration
(std::istream &istr)¶ Deserialize.
-