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.

Configuration(std::shared_ptr<Domain> domain, const argtype &args = argtype())¶: 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.

const Particle &particle_type(const int type) const¶: Return the particle associated with the type.

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.

void add(std::shared_ptr<ModelParam> param)¶: 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.

void set_physical_constants(std::shared_ptr<PhysicalConstants> constants)¶: 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.

const Particle &unique_type(const int type) const¶: Return the unique type by individual particle.

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

void add(std::shared_ptr<Group> group, std::string name = "")¶

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.

const std::vector<Select> &group_selects() const¶: Return the group-based selections.

const Select &group_select(const int index) const¶: Return the group-based selections by index.

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.

const Particle &newest_particle() const¶: Return the last particle added.

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_particles(const Select &selection)¶: Remove particle(s) in 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.

void set(std::shared_ptr<Domain> domain)¶: Set the domain.

const Domain &domain() const¶: Return the domain of the configuration.

void set_side_lengths(const Position &sides)¶: Set the domain side lengths.

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.

const std::vector<Select> &ghosts() const¶: Return ghost particles.

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()

void set_particle_type(const int particle_type, const Select &select)¶: Change select to a given particle type.

Checks

Consistency checks and tests.

void check() const¶: Check consistency of dimensions and lists.

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.