Enumerator

Detailed Description

Algorithms for enumerating objects such as Lattice, Supercell, Configuration.

Enumerators are classes that implement methods to enumerate Supercells, Configurations, and other objects by providing iterators over a range of enumerated objects. The objects are not usually stored in the enumerators but constructed as iterators are modified or dereferenced. New enumerators can be created by inheriting from:

• InputEnumeratorBase (for single-pass enumerators)
• RandomAccessEnumeratorBase (for multi-pass, random-access enumerators)

Some example enumerators are:

• ScelEnumT, ScelEnumByNameT, ScelEnumByPropsT
• ConfigEnumAllOccupations
• ConfigEnumInterpolation
• ConfigEnumStrain
• SuperConfigEnum

Enumerators are required to "know" their own name by implementing a traits class with 'name' as a const std::string member. For enumerators meant to be accessible via the 'casm enum' API, the traits class must also have a 'help' const std::string member explaining the enumerator and the input parameters, and a 'CASM::EnumInterface<EnumMethod>::run' method which implements collecting input parameters from the CLI, executing the enumerator and saving the resulting objects. Some helper functions exist to make parsing input and saving results easier:

• To collect CLI input and construct an ScelEnum which enumerates canonical Supercell: ::make_enumerator_scel_enum
• To collect CLI input and construct an SuperlatticeEnumerator which enumerates super-lattices which may not be canonical: ::make_enumerator_superlat_enum
• To save results from enumerators of unique, primitive, canonical Configurations: ::insert_unique_canon_configs
• To save results from enumerators of general Configurations: ::insert_configs

For Enumerators only meant to be used internally the required members are:

Variables:

• public: static const std::string enumerator_name; 

Functions:

•  public: std::string name() const override { return enumerator_name;
  } 

For Enumerators to be added to the API the required members are:

Variables:

• public: static const std::string enumerator_name; 

• public: static std::string interface_help(); 

Functions:

• public: std::string name() const override { return enumerator_name; }
• public: static int run(const PrimClex &primclex, const jsonParser &kwargs, const Completer::EnumOption &enum_opt);

To enable use as a plugin:

• extern "C" {
    CASM::EnumInterfaceBase *make_EnumMethod_interface() {
      return new CASM::EnumInterface<CASM::ConfigEnumAllOccupations>();
    }
  }

• To use an enumerator as a plugin for an existing CASM project, place the source code in the .casm/enumerators directory in a file named EnumMethodName.cc, where EnumMethod is the name of the enumerator class.

Modules
	Configuration Enumerators
	Enumerates Configuration.
	Supercell Enumerators
	Enumerates Supercell.
	Lattice Enumerators
	Enumerates Lattice.
	EnumEquivalents
	Enumerate equivalent objects.

Classes
class	CASM::ConfigEnumInput
class	CASM::EnumeratorBase
	Abstract base class for enumerators. More...
class	CASM::ValEnumerator< ValueType, IsConst >
class	CASM::EnumIteratorBase
class	CASM::ValEnumIterator< ValueType, IsConst >

Functions
std::vector< PermuteIterator >	CASM::make_invariant_subgroup (ConfigEnumInput const &config_enum_input)
template<typename PermuteIteratorIt >
std::vector< PermuteIterator >	CASM::make_invariant_subgroup (ConfigEnumInput const &config_enum_input, PermuteIteratorIt group_begin, PermuteIteratorIt group_end)
template<typename EnumeratorType >
bool	CASM::is_guaranteed_for_database_insert (EnumeratorType const &enumerator)
template<typename SiteContainer >
void	CASM::ConfigEnumInput::select_sites (SiteContainer const &_container)
	Select sites by "site_index" or "site_uccoord". More...
template<typename SublatticeIndexContainer >
void	CASM::ConfigEnumInput::select_sublattices (SublatticeIndexContainer const &_container)
	Select all sites on multiples sublattices. More...
	CASM::ConfigEnumInput::ConfigEnumInput (Configuration const &_configuration)
	Construct with a Configuration and all sites selected. More...
	CASM::ConfigEnumInput::ConfigEnumInput (Supercell const &_supercell)
	Construct using a Supercell's default Configuration and all sites selected. More...
	CASM::ConfigEnumInput::ConfigEnumInput (Configuration const &_configuration, std::set< Index > const &_site_index_selection)
	Construct with a Configuration and initial site selection. More...
	CASM::ConfigEnumInput::ConfigEnumInput (Supercell const &_supercell, std::set< Index > const &_site_index_selection)
Configuration const &	CASM::ConfigEnumInput::configuration () const
std::set< Index > const &	CASM::ConfigEnumInput::sites () const
void	CASM::ConfigEnumInput::clear_sites ()
	Clear site selection. After condition is no sites are selected. More...
void	CASM::ConfigEnumInput::select_all_sites ()
void	CASM::ConfigEnumInput::select_site (Index site_index)
void	CASM::ConfigEnumInput::select_site (UnitCellCoord const &site_uccord)
void	CASM::ConfigEnumInput::select_sublattice (Index sublattice_index)
	Select all sites on a sublattice. More...

Function Documentation

clear_sites()

void CASM::ConfigEnumInput::clear_sites

(

)

Clear site selection. After condition is no sites are selected.

Definition at line 72 of file ConfigEnumInput.cc.

ConfigEnumInput() [1/4]

CASM::ConfigEnumInput::ConfigEnumInput

(

Configuration const &

_configuration

)

Construct with a Configuration and all sites selected.

Definition at line 13 of file ConfigEnumInput.cc.

ConfigEnumInput() [2/4]

CASM::ConfigEnumInput::ConfigEnumInput	(	Configuration const &	_configuration,
		std::set< Index > const &	_site_index_selection = {}
	)

Construct with a Configuration and initial site selection.

Construct with a Configuration and specified sites selected

Note:

• Empty _site_index_selection results in no sites being selected

Definition at line 30 of file ConfigEnumInput.cc.

ConfigEnumInput() [3/4]

CASM::ConfigEnumInput::ConfigEnumInput

(

Supercell const &

_supercell

)

Construct using a Supercell's default Configuration and all sites selected.

Construct using a Supercell's default Configuration and all sites selected

Note:

• The Supercell default Configuration is given by Configuration::zeros(_supercell)

Definition at line 23 of file ConfigEnumInput.cc.

ConfigEnumInput() [4/4]

CASM::ConfigEnumInput::ConfigEnumInput	(	Supercell const &	_supercell,
		std::set< Index > const &	_site_index_selection = {}
	)

Construct using a Supercell's default Configuration and initial site selection

Construct using a Supercell's default Configuration and specified sites selected

Note:

• The Supercell default Configuration is given by Configuration::zeros(_supercell)
• Empty _site_index_selection results in no sites being selected

Definition at line 43 of file ConfigEnumInput.cc.

configuration()

Configuration const & CASM::ConfigEnumInput::configuration

(

)

const

Definition at line 49 of file ConfigEnumInput.cc.

is_guaranteed_for_database_insert()

template<typename EnumeratorType >

bool CASM::is_guaranteed_for_database_insert

(

EnumeratorType const &

enumerator

)

Can be specialized to return true if enumerator output is guaranteed to be canonical, primitive, etc. as required for database insertion

Definition at line 343 of file Enumerator.hh.

make_invariant_subgroup() [1/2]

std::vector< PermuteIterator > CASM::make_invariant_subgroup

(

ConfigEnumInput const &

config_enum_input

)

Returns the subgroup of the configuration factor group that does not cause any permutation between the set of selected and unselected sites of "config_enum_input"

Returns the subgroup of the configuration factor group that not cause any permutation between the set of selected and unselected sites of "config_enum_input"

Definition at line 100 of file ConfigEnumInput.cc.

make_invariant_subgroup() [2/2]

template<typename PermuteIteratorIt >

std::vector< PermuteIterator > CASM::make_invariant_subgroup	(	ConfigEnumInput const &	config_enum_input,
		PermuteIteratorIt	group_begin,
		PermuteIteratorIt	group_end
	)

Returns the subgroup of [group_begin, group_end) that does not cause any permutation between the set of selected and unselected sites of "config_enum_input"

Returns the subgroup of [group_begin, group_end] that does not cause any permutation between the set of selected and unselected sites of "config_enum_input"

Definition at line 30 of file ConfigEnumInput_impl.hh.

select_all_sites()

void CASM::ConfigEnumInput::select_all_sites

(

)

Definition at line 74 of file ConfigEnumInput.cc.

select_site() [1/2]

void CASM::ConfigEnumInput::select_site

(

Index

site_index

)

Definition at line 79 of file ConfigEnumInput.cc.

select_site() [2/2]

void CASM::ConfigEnumInput::select_site

(

UnitCellCoord const &

site_uccord

)

Definition at line 83 of file ConfigEnumInput.cc.

select_sites()

template<typename SiteContainer >

void CASM::ConfigEnumInput::select_sites

(

SiteContainer const &

_container

)

Select sites by "site_index" or "site_uccoord".

Select by "site_index" or "site_uccoord".

Definition at line 14 of file ConfigEnumInput_impl.hh.

select_sublattice()

void CASM::ConfigEnumInput::select_sublattice

(

Index

sublattice_index

)

Select all sites on a sublattice.

Definition at line 89 of file ConfigEnumInput.cc.

select_sublattices()

template<typename SublatticeIndexContainer >

void CASM::ConfigEnumInput::select_sublattices

(

SublatticeIndexContainer const &

_container

)

Select all sites on multiples sublattices.

Definition at line 20 of file ConfigEnumInput_impl.hh.

sites()

std::set< Index > const & CASM::ConfigEnumInput::sites

(

)

const

Const access selected sites, speficied by "site_index" (linear index into ConfigDoF)

Definition at line 68 of file ConfigEnumInput.cc.