Configuration

class Configuration

A Configuration contains both Particle s 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). The same is true for site types and sites.

Groups of different Particle and 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.

Tables

Shared tables that can be used in multiple VisitModel.

const std::string &name() const: Return the name of the Configuration.

void set_name(const std::string &name): Set the name of the Configuration.

void serialize(std::ostream &ostr) const: Serialize.

Configuration(std::istream &istr): Deserialize.

Arguments

The following arguments are parsed in the order listed, regardless of the order input by the user.

Domain arguments may be parsed here.
physical_constants: optional class_name of PhysicalConstants. These are typically only used in charged interactions to compute the conversion factor between squared charge over distance and energy.
particle_type: dictionary of names and files for different particle types. The dictionary syntax is name1:file_name1,name2:file_name2,etc. If only file_name are provided without names, the names will default to 0, 1, etc. Particle names must be unique. See FileParticle for description of the file required to define particles.
add_num_[type name]_particles: add this many particles of given type name. Particles are added with the coordinates in the file, so adding multiple will overlap.
xyz_file: optionally load FileXYZ if not empty (default: empty). Note that Domain tilt factors are not read by FileXYZ.
xyz_euler_file: optionally load FileXYZEuler if not empty (default: empty).
group: comma-separated list of group names. All following arguments of the group are then expected to have the name prepended with an underscore (e.g., “group=oxygen oxygen_site_type=O”).
model_param_file: input ModelParam with this file with either a three- or four-column space-separated format on each line as follows: “[parameter] [site type name] [value]” “[parameter] [site type name 1] [site type name 2] [value]” This file can be used to override the otherwise default Lorentz-Berthelot mixing rules. Mixing is always symmetric (e.g., params[i][j] == param[j][i]) Comment lines beginning with the ‘#’ character are ignored.
[parameter]: optionally set the [parameter] of all types to this value. The “[parameter]” is to be substituted for epsilon, sigma, cutoff, etc.
[parameter][site type name]: optionally set the [parameter] value of the given site type name. These are applied after (overriding) the above argument for all types.
[parameter][site type name 1]_[site type name 2]: optionally set the [parameter] value of the 1-2 mixed type. These are applied after (overriding) the above argument for single types.
wrap: wrap particle centers within domain (default: true).
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.
name: set the name of the Configuration (default: 0).

Typing

Types of sites and particles.

void add_particle_type(const std::string file_name, std::string name = ""): Add a particle type that may exist in the simulation. See FileParticle.

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.

int num_dihedral_types() const: Return the number of dihedral types.

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

const std::string &type_to_file_name(const int type) const: Return the file name used to initialize the particle types.

const std::string &particle_type_to_name(const int ptype) const: Return the name of a given particle type.

int particle_name_to_type(const std::string &name) const: Return the name of a given particle type.

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 std::string 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 std::string 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 set_model_param(const std::string name, const std::string filename, std::vector<std::string> *site_type_names = NULL)

param site_type_names:: Optionally provide a list of names of site types

void set_model_param(const std::string filename, std::vector<std::string> *site_type_names = NULL)

Set mixed model parameters using the 4-column file format described in the argument “model_param_file”

param site_type_names:: Optionally provide a list of names of site types

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.

const Site &unique_type(const int ptype, const int stype) const: Return the site of unique type by individual particle and site 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.

int site_type_to_particle_type(const int site_type) const: Return the particle type of a given site type.

std::vector<std::vector<int>> num_site_types_per_particle_type() const: Return, for each particle type, the number of sites of each type.

const std::string &site_type_to_name(const int site_type) const: Return the name of a given site type.

void site_type_names(std::vector<std::string> *names) const: Obtain the site names in order of their indices;.

int site_name_to_index(const std::string &site_name) const: Return the index of a site given the site name.

const std::string &site_index_to_name(const int particle_type, const int index) const: Return the name of a site given the particle type and site index.

int site_type_name_to_index(const std::string &site_type_name) const: For unique_type, return index of a given site type name.

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

param 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.

int group_index(const std::string &name) const: Return the index of the group with the given name.

const std::vector<std::shared_ptr<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

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.

param group:: Provide a group index to consider only a subset of the configuration.

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.

param 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.

param 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 std::vector<std::vector<double>> coords, const std::vector<std::vector<double>> eulers): Load coordinates and orientations with a per-site vector containing per-dimension vector. Requires coordinates and orientations for all sites and dimensions.

void update_positions(const Select &select, const bool no_wrap = false)

Update the positions and properties from a selection. Includes euler angles.

param no_wrap:: If true, do not wrap. If false, defer to default behavior.

void copy_particles(const Configuration &config, const bool add_missing = false)

Copy the existing particles in a given config by replacing positions. Types must match config in the same order.

param add_missing:: Add missing particles of the same type.

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.

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.

int num_cell_lists() const: Return the number of cell lists.

void increment_num_cell_lists(): Increment the number of cell lists.

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<std::shared_ptr<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 set_particle_type(const int particle_type, const Select &select): Change select to a given particle type.

Neighbor Criteria

Define and store various criteria used for defining neighbors

void add(std::shared_ptr<NeighborCriteria> neighbor_criteria): Add a NeighborCriteria.

const NeighborCriteria &neighbor_criteria(const int index) const: Return a NeighborCriteria by index in order added.

const std::vector<std::shared_ptr<NeighborCriteria>> &neighbor_criteria() const: Return a NeighborCriteria by index in order added.

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.

void check_dimensions() const: Check that the dimensions of all particle types and domain match.

std::string status_header(const std::string append = "") const: Return the header of the status for periodic output.

std::string status() const: Return the brief status for periodic output.

std::string str() const: Return the configuration in human readable format for testing.