adccore: C++ core library¶
This page contains a reference of the adccore C++ library and its classes and functions generated automatically from the adccore source code. The functions and classes discussed here are exposed to Python as the libadcc: Python bindings for adccore python module.
Reference state¶
This category lists the adccore functionality,
which imports the data from the adcc::HartreeFockSolution_i
interface into the adcc::ReferenceState
for internal use by the library.
See Connecting host programs to adcc for details how to connect
host programs to adcc.
Important classes in the process are adcc::MoSpaces
,
which collects information about the occupied and virtual
orbital spaces, and adcc::MoIndexTranslation
,
which maps orbitals indices between the ordering used by adccore
and the one used by the SCF program.
-
std::vector<size_t>
adcc
::
construct_blocks
(std::vector<size_t> block_starts_crude, size_t length, size_t max_block_size)¶ Construct a list of Tensor blocks (by identifying their starting indices) from a list of indices that identify places where a block definitely has to start and a maximal block size.
The function checks the block sizes resulting from block_starts_crude and if they are beyond max_block_size tries to split them evenly.
- Parameters
block_starts_crude
: list of crude block startslength
: Total number of indicesmax_block_size
: Maximal size of a block
-
struct
AxisRange
: public std::pair<size_t, size_t>¶ - #include <MoIndexTranslation.hh>
Very simple structure holding the range of indices for a single axis
- Note
This structure is not intended for wide use throughout the adcc code, much rather it should help to make the MoIndexTranslation code more clear. Outside this class it can be well thought of as a std::pair<size_t, size_t>.
-
struct
SimpleRange
: public std::vector<std::pair<size_t, size_t>>¶ - #include <MoIndexTranslation.hh>
Very simple structure holding an index range.
The ranges are given as lists of ranges in each axis, where for each axis the first number is the first index of the range to be taken and the second number is the first index past the range, i.e. the index range in each axis are given as half-open intervals [start, end).
- Note
This structure is not intended for wide use throughout the adcc code, much rather it should help to make the MoIndexTranslation code more clear. Outside this class it can be well thought of as a std::vector<std::pair<size_t, size_t>>.
Public Functions
-
SimpleRange
(std::vector<size_t> starts, std::vector<size_t> ends)¶ Build a Range object by specifying all starts and all ends
-
SimpleRange
(std::vector<std::pair<size_t, size_t>> in)¶ Build a Range object by providing a vector of [start, end) pairs
-
SimpleRange
()¶ Build an empty SimpleRange object
-
size_t
ndim
() const¶ Return the dimensionality, i.e. the size of the vector
-
void
push_axis
(std::pair<size_t, size_t> new_axis)¶ Add an axis by specifying its range
-
std::vector<size_t>
starts
() const¶ Get the vector of all range starts
-
std::vector<size_t>
lasts
() const¶ Get the vectors of the last indices in all axes
-
std::vector<size_t>
ends
() const¶ Get the vector of all range ends
-
struct
RangeMapping
: public std::pair<SimpleRange, SimpleRange>¶ - #include <MoIndexTranslation.hh>
Datastructure to describe a mapping of one range of indices to another range of indices.
- Note
This structure is not intended for wide use throughout the adcc code, much rather it should help to make the MoIndexTranslation code more clear. Outside this class it can be well thought of as a pair of above range objects, which are itself effectively std::vector<std::pair<size_t, size_t>>.
Public Functions
-
SimpleRange &
from
()¶ The range from which we map
-
SimpleRange &
to
()¶ The range to which we map
-
class
MoIndexTranslation
¶ - #include <MoIndexTranslation.hh>
Translation object, which helps to translate various representations of a tensorial index over orbitals subspaces. E.g. it helps to identify the spin block, reduce indices to spatial indices, translate indices or index ranges to the original ordering used in the SCF program and similar tasks.
Public Functions
Create an MoIndexTranslation object for the provided space string.
Create an MoIndexTranslation object for a list of subspace identifiers
-
std::shared_ptr<const MoSpaces>
mospaces_ptr
() const¶ Return the MoSpaces to which this MoIndexTranslation is set up
-
std::string
space
() const¶ The space used to initialise the object
-
const std::vector<std::string> &
subspaces
() const¶ The space splitup into subspaces along each dimension
-
size_t
ndim
() const¶ Number of dimensions
-
const std::vector<size_t> &
shape
() const¶ Shape of each dimension
-
std::vector<size_t>
full_index_of
(const std::vector<size_t> &index) const¶ Map an index given in the space passed upon construction to the corresponding index in the range of all MO indices (the ffff space)
-
std::vector<size_t>
block_index_of
(const std::vector<size_t> &index) const¶ Get the block index of an index
-
std::vector<size_t>
block_index_spatial_of
(const std::vector<size_t> &index) const¶ Get the spatial block index of an index
The spatial block index is the result of block_index_of modulo the spin blocks, i.e. it maps an index onto the index of the spatial blocks only, such that the resulting value is idential for two index where the MOs only differ by spin. For example the 1st core alpha and the 1st core beta orbital will map to the same value upon a call of this function.
-
std::vector<size_t>
inblock_index_of
(const std::vector<size_t> &index) const¶ Get the in-block index, i.e. the index within the tensor block
-
std::string
spin_of
(const std::vector<size_t> &index) const¶ Get the spin block of each of the index components
-
std::pair<std::vector<size_t>, std::vector<size_t>>
split
(const std::vector<size_t> &index) const¶ Split an index into block index and in-block index and return the result
-
std::tuple<std::string, std::vector<size_t>, std::vector<size_t>>
split_spin
(const std::vector<size_t> &index) const¶ Split an index into a spin block descriptor, a spatial block index and an in-block index.
-
std::vector<size_t>
combine
(const std::vector<size_t> &block_index, const std::vector<size_t> &inblock_index) const¶ Combine a block index and an in-block index into a subspace index
-
std::vector<size_t>
combine
(const std::string &spin_block, const std::vector<size_t> &block_index_spatial, const std::vector<size_t> &inblock_index) const¶ Combine a descriptor for the spin block, a spatial-only block index and an in-block index into a subspace index.
-
std::vector<size_t>
hf_provider_index_of
(const std::vector<size_t> &index) const¶ Map an index given in the space passed upon construction to the corresponding index in the HF provider, which was used to start off the adcc calculation
-
std::vector<RangeMapping>
map_range_to_hf_provider
(const SimpleRange &range) const¶ Map a range of indices to host program indices, i.e. the indexing convention used in the HfProvider / HartreeFockSolution_i classes.
Since the mapping between subspace and host program indices might not be contiguous, a list of range pairs is returned. In each pair the first entry represents a range of indices (indexed in the MO subspace) and the second entry represents the equivalent range of indices in the Hartree-Fock provider these are mapped to.
-
struct
MoSpaces
¶ - #include <MoSpaces.hh>
Information about the molecular orbitals spaces and subspaces, i.e. the occupied versus virtual orbitals, active versus frozen orbitals, core-occupied versus valence-occupied orbitals.
Public Functions
-
size_t
n_orbs
(const std::string &space = "f") const¶ The number of orbitals inside a particular orbital space
-
size_t
n_orbs_alpha
(const std::string &space = "f") const¶ The number of alpha orbitals inside a particular orbital space
-
size_t
n_orbs_beta
(const std::string &space = "f") const¶ The number of beta orbitals inside a particular orbital space
-
std::string
subspace_name
(const std::string &space = "f") const¶ Obtain a pretty name for the provided subspace
-
bool
has_core_occupied_space
() const¶ Does this object have a core-occupied space (i.e. is ready for core-valence separation)
-
bool
has_subspace
(const std::string &space) const¶ Does this object have a particular subspace
-
std::string
irrep_totsym
() const¶ Return the totally symmetric irreducible representation.
Construct an MoSpaces object from a HartreeFockSolution_i, a pointer to an AdcMemory object.
- Parameters
hf
: HartreeFockSolution_i object to useadcmem_ptr
: ADC memory keep-alive object to be used in all Tensors constructed using this MoSpaces object.core_orbitals
: List of orbitals indices (in the full fock space, original ordering of the hf object), which defines the orbitals to be put into the core space, if any. The same number of alpha and beta orbitals should be selected. These will be forcibly occupied.frozen_core_orbitals
: List of orbital indices, which define the frozen core, i.e. those occupied orbitals, which do not take part in the ADC calculation. The same number of alpha and beta orbitals has to be selected.frozen_virtuals
: List of orbital indices, which the frozen virtuals, i.e. those virtual orbitals, which do not take part in the ADC calculation. The same number of alpha and beta orbitals has to be selected.
-
std::shared_ptr<const AdcMemory>
adcmem_ptr
() const¶ Return a pointer to the memory keep-alive object
-
size_t
libtensor_irrep_index
(std::string irrep) const¶ Return the libtensor index used for the irrep string
- Note
this function is for internal usage only.
Public Members
-
std::string
point_group
¶ The name of the point group for which the data in this class has been set up.
-
std::vector<std::string>
irreps
¶ The list of all irreducible representations in this point group. The first entry will always be the totally symmetric irreducible representation.
-
bool
restricted
¶ Are the orbitals resulting from a restricted calculation, such that alpha and beta electron share the same spatial part
-
std::vector<std::string>
subspaces_occupied
¶ The list of occupied subspaces known to this object
-
std::vector<std::string>
subspaces_virtual
¶ List of virtual subspaces known to this object
-
std::vector<std::string>
subspaces
¶ List of all subspaces known to this object
-
std::map<std::string, std::vector<size_t>>
map_index_hf_provider
¶ Contains for each orbital space (e.g. f, o1) a mapping from the indices used inside the respective space to the molecular orbital index convention used in the host program, i.e. to the ordering in which the molecular orbitals have been exposed in the HartreeFockSolution_i or HfProvider object.
-
std::map<std::string, std::vector<size_t>>
map_block_start
¶ Contains for each orbital space the indices at which a new block starts. Thus this list contains at least on index, namely 0.
-
std::map<std::string, std::vector<std::string>>
map_block_irrep
¶ Contains for each orbital space the mapping from each block used inside the space to the irreducible representation it correspond to.
-
std::map<std::string, std::vector<char>>
map_block_spin
¶ Contains for each orbital space the mapping from each block used inside the space to the spin it correspond to (‘a’ is alpha and ‘b’ is beta)
-
size_t
-
class
ReferenceState
¶ - #include <ReferenceState.hh>
Struct containing data about the reference state on top of which the ADC calculation is performed
Public Functions
-
bool
restricted
() const¶ Return whether the reference is restricted or not
-
size_t
spin_multiplicity
() const¶ Return the spin multiplicity of the reference state. 0 indicates that the spin cannot be determined or is not integer (e.g. UHF)
-
bool
has_core_occupied_space
() const¶ Flag to indicate whether this is a cvs reference state
-
std::string
irreducible_representation
() const¶ Ground state irreducible representation
-
std::shared_ptr<const MoSpaces>
mospaces_ptr
() const¶ Return the MoSpaces to which this ReferenceState is set up
-
size_t
n_orbs
() const¶ Return the number of orbitals
-
size_t
n_orbs_alpha
() const¶ Return the number of alpha orbitals
-
size_t
n_orbs_beta
() const¶ Return the number of beta orbitals
-
size_t
n_alpha
() const¶ Return the number of alpha electrons
-
size_t
n_beta
() const¶ Return the number of beta electrons
-
std::vector<scalar_type>
nuclear_multipole
(size_t order) const¶ Return the nuclear contribution to the cartesian multipole moment (in standard ordering, i.e. xx, xy, xz, yy, yz, zz) of the given order.
-
double
conv_tol
() const¶ Return the SCF convergence tolerance
-
double
energy_scf
() const¶ Final total SCF energy
-
std::string
backend
() const¶ String identifying the backend used for the computation
-
std::shared_ptr<Tensor>
orbital_energies
(const std::string &space) const¶ Return the orbital energies corresponding to the provided space
-
std::shared_ptr<Tensor>
orbital_coefficients
(const std::string &space) const¶ Return the molecular orbital coefficients corresponding to the provided space (alpha and beta coefficients are returned)
-
std::shared_ptr<Tensor>
orbital_coefficients_alpha
(const std::string &space) const¶ Return the alpha molecular orbital coefficients corresponding to the provided space
-
std::shared_ptr<Tensor>
orbital_coefficients_beta
(const std::string &space) const¶ Return the beta molecular orbital coefficients corresponding to the provided space
-
std::shared_ptr<Tensor>
fock
(const std::string &space) const¶ Return the fock object of the context corresponding to the provided space.
-
std::shared_ptr<Tensor>
eri
(const std::string &space) const¶ Return the ERI (electron-repulsion integrals) contained in the context corresponding to the provided space.
-
void
import_all
() const¶ Normally the class only imports the Fock matrix blocks and electron-repulsion integrals of a particular space combination when this is requested by a call to above fock() or eri() functions.
This function call, however, instructs the class to immediately import all ERI tensors.
- Note
This typically does not need to be called explicitly.
-
std::vector<std::string>
cached_fock_blocks
() const¶ Return the list of momentarily cached fock matrix blocks
-
void
set_cached_fock_blocks
(std::vector<std::string> newlist)¶ Set the list of momentarily cached fock matrix blocks
- Note
This function is both capable to drop blocks (to save memory) and to request extra caching.
-
std::vector<std::string>
cached_eri_blocks
() const¶ Return the list of momentarily cached eri tensor blocks
-
void
set_cached_eri_blocks
(std::vector<std::string> newlist)¶ Set the list of momentarily cached ERI tensor blocks
- Note
This function is both capable to drop blocks (to save memory) and to request extra caching.
-
void
flush_hf_cache
() const¶ Tell the contained HartreeFockSolution_i object, that a larger amount of ERI data has just been computed and that the next request to further ERI tensor objects will potentially take some time, such that intermediate caches can now be flushed to save memory or other resources.
-
bool
Perturbation theory¶
adcc::LazyMp
lazily computes second-order and third-order
Møller-Plesset perturbation theory on top of the reference
held by a adcc::ReferenceState
.
-
struct
CachingPolicy_i
¶ - #include <CachingPolicy.hh>
Policy class determining, which tensors are cached and which are not
Subclassed by adcc::AlwaysCachePolicy
Public Functions
-
virtual bool
should_cache
(const std::string &tensor_label, const std::string &tensor_space, const std::string &leading_order_contraction) = 0¶ Should a tensor be stored i.e. cached in memory according to this policy object (true) or not (false).
- Parameters
tensor_label
: Label of the tensor object (e.g. t2, t2eri, …)tensor_space
: The spaces string of the tensor to estimate memory requirement (e.g. “o1o1v1v1” for “t2_o1o1v1v1”)leading_order_contraction
: The spaces involved in the most expensive contraction to compute this tensor to estimate computational scaling for computing the tensor. (e.g. “o1o1v1v1” for “t2_o1o1v1v1”)
-
virtual bool
-
class
AlwaysCachePolicy
: public adcc::CachingPolicy_i¶ - #include <CachingPolicy.hh>
Policy class, which always caches everything
-
struct
LazyMp
¶ - #include <LazyMp.hh>
A lazy Møller-Plesset perturbation theory class. The first time a particular functionality is requested, it is computed
Public Functions
Initialise a LazyMp object using a reference state. Will not compute anything unless explicitly requested
Initialise a LazyMp object using a reference state. Will not compute anything unless explicitly requested
-
double
energy_correction
(int level) const¶ Obtain the MP energy correction at a particular level
Set the t2 amplitudes tensor. This invalidates all data depending on the T2 amplitudes in this class.
- Note
Potential other caches, such as computed ADC intermediates are not automatically invalidated.
-
std::shared_ptr<Tensor>
mp2_diffdm
(std::string space) const¶ Return MP2 difference densities (in MOs)
-
std::shared_ptr<const OneParticleOperator>
mp2_diffdm_ptr
() const¶ Return MP2 difference density relative to HF as a OneParticleOperator object
-
std::shared_ptr<Tensor>
t2eri
(const std::string &space, const std::string &contraction) const¶ Return the T2 tensor with ERI tensor contraction intermediates (called pi1 to pi7 in adcman)
-
std::shared_ptr<const ReferenceState>
reference_state_ptr
() const¶ Access to the reference state on top of which the MP calculation has been performed.
-
std::shared_ptr<CachingPolicy_i>
caching_policy_ptr
() const¶ Access to the caching policy used
Set the caching policy used from now on
-
bool
has_core_occupied_space
() const¶ Has this Mp container the core-valence separation applied
AdcMatrix and matrix cores¶
adcc::AdcMatrix
sets up a representation of the ADC
matrix for a particular method. My the means of matrix cores,
which actually do the work, this allows to perform matrix-vector products
or access the diagonal of such a matrix under a common interface.
-
std::ostream &
adcc
::
operator<<
(std::ostream &o, const AdcIntermediates &im)¶ Write a descriptive string for the AdcIntermediates object to the output stream.
-
class
AdcIntermediates
¶ - #include <AdcIntermediates.hh>
Class managing intermediate expressions of the ADC matrix, which are used frequently and/or expensive to compute.
Cache functions
These functions compute the intermediates (if not already done) and cache them inside the class if the CachingPolicy says so. In this case another call to these functions will just return the pointers to the appropriate object without extra computation. In other words setting the pointers in this class to a nullptr will always trigger another computation.
-
std::shared_ptr<Tensor>
compute_adc3_m11
()¶ The ADC(3) m11 intermediate (== singles block of ADC(3) matrix
Public Functions
-
std::shared_ptr<Tensor>
-
class
AdcMatrixCoreBase
¶ - #include <AdcMatrixCoreBase.hh>
AdcMatrixCoreBase provides the interface to the actual implementations of the ADC matrix functionality
Subclassed by adcc::AdcMatrixCoreSingles, adcc::AdcMatrixCoreSinglesDoubles
Public Functions
Construct the AdcMatrixCoreBase object
- Parameters
name
: Name of the ADC methodmp_ptr_
: The LazyMp pointer describing the MP perturbation theory results
-
virtual std::vector<size_t>
shape
() const = 0¶ Return the shape of the represented matrix
-
virtual bool
has_block
(const std::string &block) const = 0¶ Return true if the referenced block exists in this matrix
-
bool
has_block
(char block) const¶ Return true if the referenced block exists in this matrix.
-
virtual std::vector<std::string>
blocks
() const = 0¶ Return the list of blocks, which exist in this matrix
-
virtual std::vector<std::string>
block_spaces
(const std::string &block) const = 0¶ Return the list of spaces involved for a particular block of the matrix
Compute the application of the singles-singles block to the vector
in
, returning the result in the vectorout
.
Compute the application of the singles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-singles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the given block of the ADC matrix.
-
virtual std::shared_ptr<Tensor>
diagonal_s
() const = 0¶ Compute the singles diagonal of the ADC matrix and return it.
-
virtual std::shared_ptr<Tensor>
diagonal_d
() const = 0¶ Compute the doubles diagonal of the ADC matrix and return it.
- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal
(std::string block) const¶ Compute the block-wise diagonal of ADC matrix.
-
virtual void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
-
std::shared_ptr<AdcIntermediates>
get_intermediates_ptr
() const¶ Get the pointer to the AdcIntermediates cache for the precomputed intermediates
Replace the currently held AdcIntermediates cache object by the supplied one. This allows to reuse intermediates from a previous calculation.
-
std::shared_ptr<const ReferenceState>
reference_state_ptr
()¶ Access to the reference state on top of which the ADC calculation has been started
-
class
AdcMatrixCoreSingles
: public adcc::AdcMatrixCoreBase¶ - #include <AdcMatrixCoreSingles.hh>
Specialisation of AdcMatrixCoreBase for ADC matrices with a singles part only
Subclassed by adcc::CvsAdcMatrixCoreSingles, adcc::GenericAdcMatrixCoreSingles
Public Functions
-
bool
has_block
(const std::string &block) const¶ Return true if the referenced block exists in this matrix
-
std::vector<std::string>
blocks
() const¶ Return the list of blocks, which exist in this matrix
Compute the application of the singles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-singles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal_d
() const¶ Compute the doubles diagonal of the ADC matrix and return it.
- Note
Might not be implemented for all matrix cores.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
Construct the AdcMatrixCoreBase object
- Parameters
name
: Name of the ADC methodmp_ptr_
: The LazyMp pointer describing the MP perturbation theory results
-
bool
-
class
AdcMatrixCoreSinglesDoubles
: public adcc::AdcMatrixCoreBase¶ - #include <AdcMatrixCoreSinglesDoubles.hh>
Specialisation of AdcMatrixCoreBase for ADC matrices with a singles and a doubles part
Subclassed by adcc::CvsAdcMatrixCoreSinglesDoubles, adcc::GenericAdcMatrixCoreSinglesDoubles
Public Functions
-
bool
has_block
(const std::string &block) const¶ Return true if the referenced block exists in this matrix
-
std::vector<std::string>
blocks
() const¶ Return the list of blocks, which exist in this matrix
Construct the AdcMatrixCoreBase object
- Parameters
name
: Name of the ADC methodmp_ptr_
: The LazyMp pointer describing the MP perturbation theory results
-
bool
-
class
CvsAdcMatrixCoreSingles
: public adcc::AdcMatrixCoreSingles¶ - #include <CvsAdcMatrixCores.hh>
Base class for CVS matrix cores with only a singles block
Subclassed by adcc::CvsAdc0MatrixCore, adcc::CvsAdc1MatrixCore
-
class
CvsAdcMatrixCoreSinglesDoubles
: public adcc::AdcMatrixCoreSinglesDoubles¶ - #include <CvsAdcMatrixCores.hh>
Base class for CVS matrix cores with a singles and a double block
Subclassed by adcc::CvsAdc2MatrixCore
-
class
CvsAdc0MatrixCore
: public adcc::CvsAdcMatrixCoreSingles¶ - #include <CvsAdcMatrixCores.hh>
Matrix core for CVS-ADC(0)
-
class
CvsAdc1MatrixCore
: public adcc::CvsAdcMatrixCoreSingles¶ - #include <CvsAdcMatrixCores.hh>
Matrix core for CVS-ADC(1)
-
class
CvsAdc2MatrixCore
: public adcc::CvsAdcMatrixCoreSinglesDoubles¶ - #include <CvsAdcMatrixCores.hh>
Matrix core for CVS-ADC(2)
Subclassed by adcc::CvsAdc2xMatrixCore
Public Functions
Compute the application of the singles-singles block to the vector
in
, returning the result in the vectorout
.
Compute the application of the singles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-singles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal_s
() const¶ Compute the singles diagonal of the ADC matrix and return it.
-
std::shared_ptr<Tensor>
diagonal_d
() const¶ Compute the doubles diagonal of the ADC matrix and return it.
- Note
Might not be implemented for all matrix cores.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
-
class
CvsAdc2xMatrixCore
: public adcc::CvsAdc2MatrixCore¶ - #include <CvsAdcMatrixCores.hh>
Matrix core for CVS-ADC(2)-x
Subclassed by adcc::CvsAdc3MatrixCore
Public Functions
Compute the application of the doubles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal_d
() const¶ Compute the doubles diagonal of the ADC matrix and return it.
- Note
Might not be implemented for all matrix cores.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
-
class
CvsAdc3MatrixCore
: public adcc::CvsAdc2xMatrixCore¶ - #include <CvsAdcMatrixCores.hh>
Matrix core for CVS-ADC(3)
Public Functions
Compute the application of the singles-singles block to the vector
in
, returning the result in the vectorout
.
Compute the application of the singles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-singles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal_s
() const¶ Compute the singles diagonal of the ADC matrix and return it.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
-
class
GenericAdcMatrixCoreSingles
: public adcc::AdcMatrixCoreSingles¶ - #include <GenericAdcMatrixCores.hh>
Base class for generic matrix cores with only a singles block
Subclassed by adcc::Adc0MatrixCore, adcc::Adc1MatrixCore
-
class
GenericAdcMatrixCoreSinglesDoubles
: public adcc::AdcMatrixCoreSinglesDoubles¶ - #include <GenericAdcMatrixCores.hh>
Base class for generic matrix cores with a singles and a doubles block
Subclassed by adcc::Adc2MatrixCore
-
class
Adc0MatrixCore
: public adcc::GenericAdcMatrixCoreSingles¶ - #include <GenericAdcMatrixCores.hh>
Matrix core for ADC(0)
-
class
Adc1MatrixCore
: public adcc::GenericAdcMatrixCoreSingles¶ - #include <GenericAdcMatrixCores.hh>
Matrix core for ADC(1)
-
class
Adc2MatrixCore
: public adcc::GenericAdcMatrixCoreSinglesDoubles¶ - #include <GenericAdcMatrixCores.hh>
Matrix core for ADC(2)
Subclassed by adcc::Adc2xMatrixCore
Public Functions
Compute the application of the singles-singles block to the vector
in
, returning the result in the vectorout
.
Compute the application of the singles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-singles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal_s
() const¶ Compute the singles diagonal of the ADC matrix and return it.
-
std::shared_ptr<Tensor>
diagonal_d
() const¶ Compute the doubles diagonal of the ADC matrix and return it.
- Note
Might not be implemented for all matrix cores.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
-
class
Adc2xMatrixCore
: public adcc::Adc2MatrixCore¶ - #include <GenericAdcMatrixCores.hh>
Matrix core for ADC(2)-x
Subclassed by adcc::Adc3MatrixCore
Public Functions
Compute the application of the doubles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal_d
() const¶ Compute the doubles diagonal of the ADC matrix and return it.
- Note
Might not be implemented for all matrix cores.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
-
class
Adc3MatrixCore
: public adcc::Adc2xMatrixCore¶ - #include <GenericAdcMatrixCores.hh>
Matrix core for ADC(3)
Public Functions
Compute the application of the singles-singles block to the vector
in
, returning the result in the vectorout
.
Compute the application of the singles-doubles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
Compute the application of the doubles-singles block to the vector
in
, returning the result in the vectorout
.- Note
Might not be implemented for all matrix cores.
-
std::shared_ptr<Tensor>
diagonal_s
() const¶ Compute the singles diagonal of the ADC matrix and return it.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the application of the ADC matrix to the amplitude vector supplied on
ins
and return the result inouts
.
-
class
AdcMatrix
¶ - #include <AdcMatrix.hh>
Class representing an ADC matrix
The ADC matrix is tiled into the following regions,
+------------+----------------+ | singles- | singles- | | singles | doubles | +------------+----------------+ | doubles- | doubles- | | singles | doubles | +------------+----------------+
where for ADC(0) and ADC(1) only the singles-singles part is present. Calling functions, which compute or make use of the doubles part in such cases leads to a std::invalid_argument.
In case no intermediates are provided to the object prior to the first payload function call, the class will automatically generate the intermediates by itself and add them to the AdcIntermediates structure referenced by intermediates_ptr. Such structure will be created in case it does not exist.
Public Functions
Construct an AdcMatrix object.
- Parameters
method
: The ADC method to useground_state_ptr
: The MP ground state to build upon
-
std::vector<size_t>
shape
() const¶ Return the shape of the represented matrix
-
bool
has_block
(const std::string &block) const¶ Return true if the referenced block exists in this matrix
-
std::vector<std::string>
blocks
() const¶ Return the list of blocks, which exist in this matrix
-
std::vector<std::string>
block_spaces
(const std::string &block) const¶ Return the list of spaces involved for a particular block of the matrix
Apply a block of the ADC matrix (e.g. the singles-singles block or the singles-doubles block. The result is stored in a pre-allocated tensor.
- Parameters
block
: Block specification, may take the values “ss”, “sd”, “ds”, “dd”. May not take all values for all ADC variants.in
: Input tensor, rhs of the expressionout
: Output tensor, result of the application.
-
void
compute_matvec
(const AmplitudeVector &ins, const AmplitudeVector &outs) const¶ Compute the matrix-vector product of the ADC matrix with an excitation amplitude. The rhs amplitude parts are provided as std::vector, containing singles, doubles, … part and so are resulting amplitudes. The result is stored in a pre-allocated tensor.
- Parameters
ins
: Input tensors, one per amplitude part (singles, doubles)outs
: Output tensors as a shared pointers
-
std::string
method
() const¶ Access to the adc method this class represents
-
bool
is_core_valence_separated
() const¶ Is the core-valence separation applied in this matrix
-
std::shared_ptr<const ReferenceState>
reference_state_ptr
() const¶ Access to the reference state on top of which the ADC calculation has been started
-
std::shared_ptr<const LazyMp>
ground_state_ptr
() const¶ Obtain the pointer to the MP ground state upon which this ADC matrix is based.
-
std::shared_ptr<AdcIntermediates>
get_intermediates_ptr
() const¶ Get the pointer to the AdcIntermediates cache for the precomputed intermediates
Replace the currently held AdcIntermediates cache object by the supplied one. This allows to reuse intermediates from a previous calculation.
ADC guess setup¶
Apply the spin projection required to make the doubles part of an amplitude vector consist of components for a singlet state only.
- Note
This function assumes a restricted reference with a closed-shell ground state (e.g. RHF).
- Parameters
tensor
: The tensor to apply the symmetrisation toblock
: The block of an amplitude this tensor representsspin_kind
: The kind of spin to enforce
-
std::vector<std::shared_ptr<Symmetry>>
adcc
::
guess_symmetries
(const AdcMatrix &matrix, const AdcGuessKind &kind)¶ Return the symmetries for setting up guess vectors. The first entry is the singles symmetry the second the doubles symmetry and so on.
-
AmplitudeVector
adcc
::
guess_zero
(const AdcMatrix &matrix, const AdcGuessKind &kind)¶ Return an AmplitudeVector object filled with zeros, but where the symmetry has been properly set up to meet the requirements of the AdcGuessKind object
-
std::vector<AmplitudeVector>
adcc
::
guesses_from_diagonal
(const AdcMatrix &matrix, const AdcGuessKind &kind, std::string block, size_t n_guesses, scalar_type degeneracy_tolerance)¶ Obtain guesses by inspecting a block of the diagonal of the passed ADC matrix. The symmetry of the returned vectors is already set-up properly. Note that this routine may return fewer vectors than requested in case the requested number could not be found.
matrix AdcMatrix for which guesses are to be constructed kind AdcGuessKind object describing the kind of guesses to be constructed block The block of the diagonal to investigate. May be “s” (singles) or “d” (doubles). n_guesses The number of guesses to look for. degeneracy_tolerance Tolerance for two entries of the diagonal to be considered degenerate, i.e. identical.
-
struct
AdcGuessKind
¶ - #include <guess_zero.hh>
Struct, which collects information about the kind of guess vectors to be constructed.
To make the collected quantities more relatable, here are common profiles:
Singlet RHF reference
for computing singlet excited states: spin_change == 0 and spin_block_symmetrisation == “symmetric”
for computing triplet excited states: spin change == 0 and spin_block_symmetrisation == “antisymmetric”
UHF reference
for computing any kind of excited state: spin_change == 0 and spin_symmetrisation == “none”
for spin-flip states: spin_change == -1 and spin_symmetrisation == “none”
- Note
The information is collected in the sense of “what the guess vectors should
look like” as opposed to “what excitations are computed with such vectors”. The reasoning is that the latter also depends on the reference, which, however, does not influence the way the guess algorithms need to find the guess vectors.
Public Members
-
std::string
irrep
¶ String describing the irreducable representation to consider
-
float
spin_change
¶ The spin change to enforce in an excitation. Typical values are 0 and -1.
-
int
spin_change_twice
¶ Twice the value of spin_change as an integer
-
std::string
spin_block_symmetrisation
¶ Symmetrisation to enforce between equivalent spin blocks, which all yield the desired spin_change. E.g. if spin_change == 0, then both the alpha->alpha and beta->beta blocks of the singles part of the excitation vector achieve this spin change. The symmetry specified with this parameter will then be imposed between the a-a and b-b blocks. Valid values are “none”, “symmetric” and “antisymmetric”, where “none” enforces no symmetry.
ISR and one-particle densities¶
Compute the ground-state to excited state one-particle transition-density matrix (optdm) at the ADC level of theory given by the method_ptr.
- Parameters
method
: The ADC method to useground_state_ptr
: The MP ground state to build uponexcitation_amplitude
: The excitation amplitude, given as a std::vector of blocks (singles, doubles, …)intermediates_ptr
: Adc intermediates to reuse during property calculation
Compute the modified transition moments (MTM)
- Parameters
method
: The ADC method to useground_state_ptr
: The MP ground state to build uponop_ptr
: The operator for which the MTM should be computed
Compute the excited state to excited state one-particle transition-density matrix (optdm) at the ADC level of theory given by the method_ptr.
- Parameters
method
: The ADC method to useground_state_ptr
: The MP ground state to build uponexcitation_amplitude_from
: The excitation amplitude, given as a std::vector of blocks (singles, doubles, …) from which the electronic transition startsexcitation_amplitude_to
: The excitation amplitude, given as a std::vector of blocks (singles, doubles, …) where the electronic transition ends.intermediates_ptr
: Adc intermediates to reuse during property calculation
Compute the one-particle density matrix of a particular state at the ADC level of theory given by the method_ptr.
- Parameters
method
: The ADC method to useground_state_ptr
: The MP ground state to build uponexcitation_amplitude
: The excitation amplitude, given as a std::vector of blocks (singles, doubles, …)intermediates_ptr
: Adc intermediates to reuse during property calculation
-
struct
OneParticleOperator
¶ - #include <OneParticleOperator.hh>
Container for a one-particle operator in MO representation. This container is used both for state density matrices as well as for transition-density matrices.
This object is a map from a block label (like o1o1) to the actual tensor object.
Public Functions
Construct an empty OneParticleOperator object. Will construct an object with all blocks initialised as zero blocks.
- Parameters
mospaces
: MoSpaces objectis_symmetric
: Is the operator symmetriccartesian_transformation
: The cartesian function according to which the operator transforms. See make_symmetry_operator for details.
-
size_t
ndim
() const¶ Number of dimensions
-
std::vector<size_t>
shape
() const¶ Shape of each dimension
-
size_t
size
() const¶ Number of elements
-
std::shared_ptr<OneParticleOperator>
copy
() const¶ Return a deep copy of this OneParticleOperator.
This can be used to conveniently add tensor corrections on top of existing OneParticleOperator objects.
-
std::shared_ptr<Tensor>
block
(std::string block) const¶ Get a particular block of the one-particle operator, throwing an invalid_argument in case the block is a known zero block
-
std::shared_ptr<Tensor>
operator[]
(std::string label)¶ Get a particular block of the one-particle operator. It allocates and stores a tensor representing a zero block on the fly if required.
Set a particular block of the one-particle operator
-
void
set_zero_block
(std::vector<std::string> blocks)¶ Set the list of specified blocks to zero without storing an explicit zero tensor for them. If previously a tensor has been stored for them it will be purged.
-
void
set_zero_block
(std::string block)¶ The version of
set_zero_block
for only a single block
-
bool
is_zero_block
(std::string block) const¶ Return whether the specified block is a block flagged to be exactly zero using the set_zero_block function.
-
bool
has_block
(std::string block) const¶ Check weather a particular block exists
-
std::vector<std::string>
blocks
() const¶ Return the list of all registered blocks
-
std::vector<std::string>
blocks_nonzero
() const¶ Return the list of all registered not-zero blocks
-
std::vector<std::string>
orbital_subspaces
() const¶ Return the list of all orbital subspaces contained in the operator
-
bool
is_symmetric
() const¶ Is the operator represented by this object symmetric If true then certain density matrices (like v1o1) might be missing, since they are equivalent to already existing blocks (such as o1v1 in our example)
-
std::string
cartesian_transform
() const¶ The cartesian function according to which the operator transforms. See make_symmetry_operator for details.
Transform this operator object to the AO basis, which was used to obtain the provided reference state.
- Return
A pair of matrices in the AO basis. The first is the matrix for alpha spin, the second for beta spin.
Transform this operator object to the AO basis using the coefficient tensors provided for each molecular orbital subspace. The coefficient tensors should be provided via a mapping from the subspace identifier to the actual coefficient for each spin part. E.g. “o1_a” should map to the coefficient “c_o1b” which are the alpha coefficients for the first occupied orbital subspace.
- Return
A pair of matrices in the AO basis. The first is the matrix for alpha spin, the second for beta spin.
-
void
export_to
(scalar_type *memptr, size_t size) const¶ Extract the operator to plain memory provided by the given pointer.
- Note
This will return a full, dense tensor. At least size elements of space are assumed at the provided memory location. The data is stored in row-major (C-like) format
Tensor interface¶
The generalised adcc::Tensor
interface
used by adcc and adccore to perform tensor operations.
Return the Symmetry object for the orbital energies tensor for the passed orbital subspace.
Return the Symmetry object for the orbital coefficient tensor for the passed orbital subspace.
- Parameters
mospaces_ptr
: MoSpaces pointerspace
: Space to use (e.g. fb or o1b)n_bas
: Number of AO basis functionsblocks
: Which blocks of the coefficients to return. Valid values are “ab” to return a tensor for both alpha and beta block as a block-diagonal tensor, “a” to only return a tensor for only alpha block and “b” for only the beta block. The fourth option is “abstack”, which returns the symmetry for a alpha block stacked on top of a beta block (This is the convention used by adcman).
Return the Symmetry object for the (antisymmetrised) electron-repulsion integral tensor in the physicists’ indexing convention for the passed orbital subspace.
Return the Symmetry object for the (non-antisymmetrised) electron-repulsion integral tensor in the physicists’ indexing convention for the passed orbital subspace.
- Note
This is not the symmetry of the eri objects in adcc. This is only needed for some special routines importing the ERI tensor into adcc. Use it only if you know you need it.
Return the Symmetry object for a MO spaces block of a one-particle operator
Note: This can be used for the Fock matrix with operator_class = “1”
- Parameters
mospaces_ptr
: MoSpaces pointerspace
: Space to use (e.g. o1o1 or o1v1)symmetric
: Is the tensor symmetric (only in effect if both space axes identical). false disables a setup of permutational symmetry.cartesian_transformation
: The cartesian function accordung to which the operator transforms. Valid values are: “1” Totally symmetric (default) “x”, “y”, “z” Coordinate axis “xx”, “xy”, “yz” … Products of two coordinate axis “Rx”, “Ry”, “Rz” Rotations about the coordinate axis
Return the symmetry object for an operator in the AO basis. The object will represent a block-diagonal matrix of the form ( M 0 ) ( 0 M ). where M is an n_bas x n_bas block and is indentical in upper-left and lower-right.
- Parameters
mospaces_ptr
: MoSpaces pointern_bas
: Number of AO basis functionssymmetric
: Is the tensor symmetric (only in effect if both space axes identical). false disables a setup of permutational symmetry.
Construct an uninitialised tensor using a Symmetry object
Construct an uninitialised tensor using no symmetry at all
Construct a tensor initialised to zero using a Symmetry object
-
class
Symmetry
¶ - #include <Symmetry.hh>
Container for Tensor symmetry
Public Functions
Create an empty symmetry object for a Tensor with the provided space string
Create an empty symmetry object for a Tensor with the provided space string, optionally using a map to supply the number of orbitals for some additional axes.
For the additional axis the pair contains either two numbers (for the number of alpha and beta orbitals in this axis) or only one number and a zero (for an axis, which as only one spin kind, alpha or beta).
-
const std::vector<AxisInfo>
axes
() const¶ Return the info about each of the contained tensor axes in order
-
std::string
space
() const¶ The space used to initialise the object
-
const std::vector<std::string> &
subspaces
() const¶ The space splitup into subspaces along each dimension
-
size_t
ndim
() const¶ Number of dimensions
-
std::vector<size_t>
shape
() const¶ Shape of each dimension
-
void
clear
()¶ Clear all symmetry elements stored in the datastructure
-
bool
empty
() const¶ Is the datastructure empty, i.e. are there no symmetry elements stored in here
-
void
set_irreps_allowed
(std::vector<std::string> irreps)¶ Set the list of irreducible representations, for which the symmetry shall be non-zero. If this is not set all irreps will be allowed
-
std::vector<std::string>
irreps_allowed
() const¶ Get the list of allowed irreducible representations. If this empty, all irreps are allowed.
-
bool
has_irreps_allowed
() const¶ Is a restriction to irreps set
-
void
clear_irreps_allowed
()¶ Clear the restriction to particular irreps, i.e. allow all irreps
-
void
set_permutations
(std::vector<std::string> permutations)¶ Set a list of index permutations, which do not change the tensor. A minus may be used to indicate anti-symmetric permutations with respect to the first (reference) permutation.
For example the vector {“ij”, “ji”} defines a symmetric matrix and {“ijkl”, “-jikl”, “-ijlk”, “klij”} the symmetry of the ERI tensor. Not all permutations need to be given to fully describe the symmetry. The check for errors and conflicts is only rudimentary at the moment, however.
-
std::vector<std::string>
permutations
() const¶ Return the list of equivalent permutations
-
bool
has_permutations
() const¶ Are there equivalent permutations set up
-
void
clear_permutations
()¶ Clear the equivalent permutations
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
permutations_parsed
() const¶ Return the list of equivalent permutations in a parsed internal format.
- Note
Internal function. May go or change at any time
-
void
set_spin_block_maps
(std::vector<std::tuple<std::string, std::string, double>> spin_maps)¶ Set lists of tuples of the form {“aaaa”, “bbbb”, -1.0}, i.e. two spin blocks followed by a factor. This maps the second onto the first with a factor of -1.0 between them.
-
std::vector<std::tuple<std::string, std::string, double>>
spin_block_maps
() const¶ Return the list of equivalent spin blocks
-
bool
has_spin_block_maps
() const¶ Are there equivalent spin blocks set up?
-
void
clear_spin_block_maps
()¶ CLear the equivalent spin blocks
-
void
set_spin_blocks_forbidden
(std::vector<std::string> forbidden)¶ Mark spin-blocks as forbidden (i.e. enforce them to stay zero). Blocks are give as a list in the letters ‘a’ and ‘b’, e.g. {“aaaa”, “abba”}
-
std::vector<std::string>
spin_blocks_forbidden
() const¶ Return the list of currently forbidden spin blocks
-
bool
has_spin_blocks_forbidden
() const¶ Are there forbidden spin blocks set up?
-
void
clear_spin_blocks_forbidden
()¶ Clear the forbidden spin blocks, i.e. allow all blocks
-
class
Tensor
¶ - #include <Tensor.hh>
The tensor interface used by adccore
Subclassed by adcc::TensorImpl< N >
Interface of a tensor, which is exposed to python.
-
size_t
ndim
() const¶ Number of dimensions
-
const std::vector<size_t> &
shape
() const¶ Shape of each dimension
-
size_t
size
() const¶ Number of elements
-
std::vector<std::string>
subspaces
() const¶ Subspace labels identifying each axis
-
std::string
space
() const¶ Space to which the tensor is initialised
-
const std::vector<std::string> &
flags
() const¶ Set some flags for playing around
-
virtual std::shared_ptr<Tensor>
empty_like
() const = 0¶ Return a new tensor with the same dimensionality and symmetry as the passed tensor. The elements have undefined values.
-
virtual std::shared_ptr<Tensor>
nosym_like
() const = 0¶ Return a new tensor with same dimensionality and shape (and bispace) but without any symmetry copied over
-
std::shared_ptr<Tensor>
zeros_like
() const¶ Return a new tensor with the same dimensionality and symmetry as the passed tensor and all elements set to zero.
-
std::shared_ptr<Tensor>
ones_like
() const¶ Return a new tensor with the same dimensionality and symmetry as the passed tensor and all elements set to one.
-
virtual void
set_mask
(std::string mask, scalar_type value) = 0¶ Set a mask into a tensor to a specific value. The mask to set is defined by the mask string. Repetitive indices define the values to be set. E.g. for a 6D tensor the mask string “iijkli” would set all elements T_{iijkli} for all ijkl to the given value.
-
void
fill
(scalar_type value)¶ Shift the elements matched by a mask into a tensor by a specific value. The mask to set is defined by the mask string. Repetitive indices define the values to be shifted. E.g. for a 6D tensor the mask string “iijkli” would shift all elements T_{iijkli} for all ijkl by the given value. Fill the tensor with a particular value, adhereing to symmetry.
-
virtual void
set_random
() = 0¶ Set the tensor to random data preserving symmetry
-
virtual std::shared_ptr<Tensor>
scale
(scalar_type c) const = 0¶ Scale tensor by a scalar value and return the result
Add another tensor and return the result
Add a linear combination to the represented tensor and store the result. Note that unlike
add
andscale
this operation is not lazy and is provided for optimising on cases where a lazy linear combination introduces a too large overhead.
Multiply another tensor elementwise and return the result
Divide another tensor elementwise and return the result
-
virtual std::shared_ptr<Tensor>
transpose
(std::vector<size_t> axes) const = 0¶ Return a transpose form of this tensor
- Parameters
axes
: New permutation of the dimensions of this tensor (e.g. (1,0,2,3) will permute dimension 0 and 1 and keep the others) If missing, just reverse the dimension order.
Return the tensordot of this tensor with another
- Parameters
axes
: Axes to contract over. The first vector refers to the axes of this tensor, the second vector to the axes of the other tensor.
Compute the Frobenius or l2 inner product with a list of other tensors, returning the results as a scalar array
-
virtual double
trace
(std::string contraction) const = 0¶ Return the full trace of a tensor
- Parameters
contraction
: Indices to contract over using Einstein summation convention, e.g. “abab” traces over the 1st and 3rd and 2nd and 4th axis.
Compute the direct sum of this tensor with another tensor. All axes are used in the order of appearance (this and then other).
-
virtual std::shared_ptr<Tensor>
symmetrise
(const std::vector<std::vector<size_t>> &permutations) const = 0¶ Symmetrise with respect to the given index permutations by adding the elements resulting from appropriate index permutations.
Examples for permutations. Take a rank-4 tensor T_{ijkl} {{0,1}} Permute the first two indices, i.e. form 0.5 * (T_{ijkl} + T_{jikl}) {{0,1}, {2,3}} Form 0.5 * (T_{ijkl} + T_{jilk})
- Parameters
permutations
: The list of permutations to be applied simultaneously
- Note
Unlike the implementation in libtensor, this function includes the prefactor 0.5
-
virtual std::shared_ptr<Tensor>
antisymmetrise
(const std::vector<std::vector<size_t>> &permutations) const = 0¶ Antisymmetrise with respect to the given index permutations and return the result. For details with respect to the format of the permutations, see symmetrise. In this case the output tensor will be antisymmetric with respect to these permutations.
- Note
Unlike the implementation in libtensor, this function includes the prefactor 0.5
-
virtual void
evaluate
() const = 0¶ Make sure to evaluate this tensor in case this has not yet happened
-
virtual bool
needs_evaluation
() const = 0¶ Check weather the object represents an evaluated expression or not.
-
virtual void
set_immutable
() = 0¶ Flag the tensor as immutable, allows some optimisations to be performed
-
virtual bool
is_mutable
() const = 0¶ Is the tensor mutable
-
virtual void
set_element
(const std::vector<size_t> &idx, scalar_type value) = 0¶ Set the value of a single tensor element
- Note
This is a slow function and should be avoided.
-
virtual scalar_type
get_element
(const std::vector<size_t> &tidx) const = 0¶ Get the value of a single tensor element
- Note
This is a slow function and should be avoided.
-
virtual bool
is_element_allowed
(const std::vector<size_t> &tidx) const = 0¶ Return whether the element referenced by tidx is allowed (non-zero) by the symmetry of the Tensor or not.
-
virtual std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_absmax
(size_t n, bool unique_by_symmetry = true) const = 0¶ Get the n absolute largest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
virtual std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_absmin
(size_t n, bool unique_by_symmetry = true) const = 0¶ Get the n absolute smallest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
virtual std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_max
(size_t n, bool unique_by_symmetry = true) const = 0¶ Get the n largest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
virtual std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_min
(size_t n, bool unique_by_symmetry = true) const = 0¶ Get the n smallest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
virtual void
export_to
(scalar_type *memptr, size_t size) const = 0¶ Extract the tensor to plain memory provided by the given pointer.
- Note
This will return a full, dense tensor. At least size elements of space are assumed at the provided memory location. The data is stored in row-major (C-like) format
-
virtual void
export_to
(std::vector<scalar_type> &output) const¶ Extract the tensor into a std::vector, which will be resized to fit the data.
- Note
All data is stored in row-major (C-like) format
-
virtual void
import_from
(const scalar_type *memptr, size_t size, scalar_type tolerance = 0, bool symmetry_check = true) = 0¶ Import the tensor from plain memory provided by the given pointer. The memory will be copied and all existing data overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
This function requires a full, dense tensor with the data stored in row-major (C-like) format.
- Parameters
memptr
: Full, dense memory pointer to the tensor data to be imported.size
: Size of the dense memory.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
virtual void
import_from
(const std::vector<scalar_type> &input, scalar_type tolerance = 0, bool symmetry_check = true)¶ Import the tensor from plain memory provided by the given vector. The memory will be copied and all existing data overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
This function requires a full, dense tensor with the data stored in row-major (C-like) format.
- Parameters
input
: Input data in a linearised vectortolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
virtual void
import_from
(std::function<void(const std::vector<std::pair<size_t, size_t>>&, scalar_type *)> generator, scalar_type tolerance = 0, bool symmetry_check = true, ) = 0¶ Import the tensor from a generator functor. All existing data will be overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
The generator is required to produce data in row-major (C-like) format at a designated memory location.
- Parameters
generator
: Generator functor. The functor is called with a list of ranges for each dimension. The ranges are half-open, left-inclusive and right-exclusive. The corresponding data should be written to the passed pointer into raw memory. This is an advanced functionality. Use only if you know what you are doing.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
virtual std::string
describe_symmetry
() const = 0¶ Return a std::string providing hopefully helpful information about the symmetries stored inside the tensor object.
-
virtual std::string
describe_expression
(std::string stage = "unoptimised") const = 0¶ Return a std::string providing hopefully helpful information about the expression tree stored inside the tensor object. Valid values for stage are “unoptimised”, “optimised”, “evaluation” returning the unoptimised expression tree as stored, an optimised form of it or the tree as used actually for evaluating the expression.
-
std::shared_ptr<const AdcMemory>
adcmem_ptr
() const¶ Return a pointer to the memory keep-alive object
-
const std::vector<AxisInfo> &
axes
() const¶ Return the axes info for this tensor
Public Functions
Construct a tensor interface class.
- Parameters
adcmem_ptr
: Memory to use for the tensor.axes
: Information about the tensor axes.
-
size_t
Utilities¶
-
typedef double
adcc
::
real_type
¶ The real type to use
-
typedef double
adcc
::
scalar_type
¶ The scalar type to use
-
MethodParsed
adcc
::
parse_method
(std::string method)¶ Parse a method string and return a MethodParsed object containing some useful information in the form of flat data.
-
template<typename
RandomAccessIterator
, typenameCompare
>
std::vector<size_t>adcc
::
argsort
(const RandomAccessIterator first, const RandomAccessIterator last, Compare cmp)¶ Argsort returns the index sequence, which would sort the range of elements provided.
Performs an indirect sorting of the range provided by the two iterators. The vectors of indices returned gives the ordering of the iterator range, which would give a sorted range. By the default less is used as the comparator.
E.g. It the range runs over the elements { “d”, “a”, “c”, “b” }, then the returned indices would be { 1, 3, 2, 0 } (if less is used as the comparator).
-
template<typename
RandomAccessIterator
>
std::vector<size_t>adcc
::
argsort
(const RandomAccessIterator first, const RandomAccessIterator last)¶ Sort a range using the argsort function with the default comparator (less).
-
std::string
adcc
::
shape_to_string
(const std::vector<size_t> &shape)¶ Convert a std::vector<size_t> representing a tensor shape to a string
-
class
AdcMemory
¶ - #include <AdcMemory.hh>
Manages memory for adc calculations.
This class has to remain in scope for as long as the allocated memory is needed. Normally this is achieved by keeping some sort of keep-alive shared pointer in the private context of all classes which require access to this memory. All changes to the environment are undone when the class goes out of scope.
- Note
Undefined behaviour may result if this class is ever initialised twice.
Public Functions
-
AdcMemory
(std::string pagefile_directory, size_t max_memory, size_t tbs_param = 16)¶ Setup the class and directly call initialise with the default allocator
-
std::string
allocator
() const¶ Return the allocator to which the class is initialised.
-
size_t
max_memory
() const¶ Return the max_memory parameter value to which the class was initialised.
- Note
This value is only a meaningful upper bound if allocator() != “standard”
-
std::string
pagefile_directory
() const¶ Return the pagefileprefix value
- Note
This value is only meaningful if allocator() != “standard”
-
size_t
tbs_param
() const¶ Return the tbs_param value
-
size_t
contraction_batch_size
() const¶ Get the contraction batch size, this is the number of tensor blocks, which are processed in a batch in a tensor contraction.
-
void
set_contraction_batch_size
(size_t bsize)¶ Set the contraction batch size
-
void
initialise
(std::string pagefile_directory, size_t max_memory, size_t tbs_param = 16, std::string allocator = "default")¶ Setup the environment for the memory management.
- Note
For some allocators
pagefile_directory
andmax_memory
are not supported and thus ignored.- Note
”libxm” and “libvmm” are extra features, which are not available in a default setup.
- Parameters
pagefile_directory
: File prefix for page filesmax_memory
: The maximal memory adc makes use of (in bytes).tbs_param
: The tensor block size parameter. This parameter roughly has the meaning of how many indices are handled together on operations. A good value seems to be 16.allocator
: The allocator to be used. Valid values are “libxm”, “libvmm”, “standard” and “default”, where “default” uses a default chosen from the first three.
-
struct
MethodParsed
¶ - #include <parse_method.hh>
Parsed information about an ADC method
-
class
ThreadPool
¶ - #include <ThreadPool.hh>
Pool managing how many threads may be used for calculations.
Public Functions
-
ThreadPool
(size_t n_running, size_t n_total)¶ Initialise the thread pool.
- Parameters
n_running
: The total number of running threads to employn_total
: The total number of worker threads to use (Either running or ready)
-
void
reinit
(size_t n_running, size_t n_total)¶ Reinitialise the thread pool.
- Parameters
n_running
: The total number of running threads to employn_total
: The total number of worker threads to use (Either running or idle)
-
ThreadPool
()¶ Initialise a thread pool without parallelisation
-
size_t
n_running
() const¶ Return the number of running threads.
-
size_t
n_total
() const¶ Return the total number of worker threads (running or ready)
-
-
class
Timer
¶ - #include <Timer.hh>
Minimalistic timer class: Just records the start and stop times for tasks, i.e. the intervals they ran
Public Functions
-
Timer
()¶ Construct an empty timer object
-
void
start
(const std::string &task)¶ Start a particular task
-
double
stop
(const std::string &task)¶ Stop the task again
Public Members
-
double
time_construction
¶ Time when this class was constructed
-
std::map<std::string, std::vector<std::pair<double, double>>>
intervals
¶ The intervals stored for a particular key
-
std::map<std::string, double>
start_times
¶ The start time stored for each key
Public Static Functions
-
static double
now
()¶ A float representing the current time on the clock used for measurement. For consistency, this function should always be used to obtain a representation of “now”. The unit is seconds.
-
-
class
RecordTime
¶ - #include <Timer.hh>
RAI-like class for timing tasks. Construction starts the timer, destruction ends it automatically. It is assumed that the passed task has a longer lifetime than the RecordTime object
Public Functions
Metadata access¶
These classes and functions provide access to metadate about adccore.
-
std::vector<std::string>
adcc
::
__features__
()¶ Return the list of compiled-in features
Return the authors string
-
std::string
adcc
::
__email__
()¶ Return the email string
-
struct
version
¶ - #include <metadata.hh>
Version information
Public Static Functions
-
static int
major_part
()¶ Return the major part of the version
-
static int
minor_part
()¶ Return the minor part of the version
-
static int
patch_part
()¶ Return the patch part of the version
-
static bool
is_debug
()¶ Is the compiled version a Debug version
-
static std::string
version_string
()¶ Return the version as a string
-
static int
-
struct
Component
¶ - #include <metadata.hh>
Data about a library or third-party component
Public Members
-
std::string
name
¶ The name of the component.
-
std::string
version
¶ The version string.
The authors.
-
std::string
description
¶ A brief description.
-
std::string
doi
¶ DOI to a publication.
-
std::string
website
¶ Website of the upstream source.
-
std::string
licence
¶ A short identifier of the licence.
-
std::string
Tensor implementation using libtensor¶
This section describes the implementation of the
Tensor functionality of adcc::Tensor
using the libtensor tensor library.
-
std::map<size_t, std::string>
adcc
::
setup_point_group_table
(libtensor::product_table_container &ptc, const std::string &point_group)¶ Setup point group symmetry table inside libtensor and return the irrep mapping as libtensor needs it.
-
template<size_t
N
>
libtensor::bispace<N>adcc
::
as_bispace
(const std::vector<AxisInfo> &axes)¶ Form a bispace from a list of AxisInfo representing the axes of a tensor
Translate a adcc::Symmetry object into a shared pointer of the libtensor symmetry object
Construction of the tensor implementation class
- Note
This constructor is for experts only. Non-experts should use the make_tensor method instead.
-
std::shared_ptr<Tensor>
adcc::TensorImpl
::
empty_like
() const¶ Return a new tensor with the same dimensionality and symmetry as the passed tensor. The elements have undefined values.
-
std::shared_ptr<Tensor>
adcc::TensorImpl
::
nosym_like
() const¶ Return a new tensor with same dimensionality and shape (and bispace) but without any symmetry copied over
-
void
adcc::TensorImpl
::
set_mask
(std::string mask, scalar_type value)¶ Set a mask into a tensor to a specific value. The mask to set is defined by the mask string. Repetitive indices define the values to be set. E.g. for a 6D tensor the mask string “iijkli” would set all elements T_{iijkli} for all ijkl to the given value.
-
void
adcc::TensorImpl
::
set_random
()¶ Set the tensor to random data preserving symmetry
-
std::shared_ptr<Tensor>
adcc::TensorImpl
::
scale
(scalar_type c) const¶ Scale tensor by a scalar value and return the result
Add another tensor and return the result
Multiply another tensor elementwise and return the result
Divide another tensor elementwise and return the result
Add a linear combination to the represented tensor and store the result. Note that unlike
add
andscale
this operation is not lazy and is provided for optimising on cases where a lazy linear combination introduces a too large overhead.
-
std::shared_ptr<Tensor>
adcc::TensorImpl
::
transpose
(std::vector<size_t> axes) const¶ Return a transpose form of this tensor
- Parameters
axes
: New permutation of the dimensions of this tensor (e.g. (1,0,2,3) will permute dimension 0 and 1 and keep the others) If missing, just reverse the dimension order.
Compute the direct sum of this tensor with another tensor. All axes are used in the order of appearance (this and then other).
Return the tensordot of this tensor with another
- Parameters
axes
: Axes to contract over. The first vector refers to the axes of this tensor, the second vector to the axes of the other tensor.
Compute the Frobenius or l2 inner product with a list of other tensors, returning the results as a scalar array
-
std::shared_ptr<Tensor>
adcc::TensorImpl
::
symmetrise
(const std::vector<std::vector<size_t>> &permutations) const¶ Symmetrise with respect to the given index permutations by adding the elements resulting from appropriate index permutations.
Examples for permutations. Take a rank-4 tensor T_{ijkl} {{0,1}} Permute the first two indices, i.e. form 0.5 * (T_{ijkl} + T_{jikl}) {{0,1}, {2,3}} Form 0.5 * (T_{ijkl} + T_{jilk})
- Parameters
permutations
: The list of permutations to be applied simultaneously
- Note
Unlike the implementation in libtensor, this function includes the prefactor 0.5
-
std::shared_ptr<Tensor>
adcc::TensorImpl
::
antisymmetrise
(const std::vector<std::vector<size_t>> &permutations) const¶ Antisymmetrise with respect to the given index permutations and return the result. For details with respect to the format of the permutations, see symmetrise. In this case the output tensor will be antisymmetric with respect to these permutations.
- Note
Unlike the implementation in libtensor, this function includes the prefactor 0.5
-
double
adcc::TensorImpl
::
trace
(std::string contraction) const¶ Return the full trace of a tensor
- Parameters
contraction
: Indices to contract over using Einstein summation convention, e.g. “abab” traces over the 1st and 3rd and 2nd and 4th axis.
-
void
adcc::TensorImpl
::
evaluate
() const¶ Make sure to evaluate this tensor in case this has not yet happened
-
bool
adcc::TensorImpl
::
needs_evaluation
() const¶ Check weather the object represents an evaluated expression or not.
-
void
adcc::TensorImpl
::
set_immutable
()¶ Flag the tensor as immutable, allows some optimisations to be performed
-
bool
adcc::TensorImpl
::
is_mutable
() const¶ Is the tensor mutable
-
void
adcc::TensorImpl
::
set_element
(const std::vector<size_t> &idx, scalar_type value)¶ Set the value of a single tensor element
- Note
This is a slow function and should be avoided.
-
scalar_type
adcc::TensorImpl
::
get_element
(const std::vector<size_t> &tidx) const¶ Get the value of a single tensor element
- Note
This is a slow function and should be avoided.
-
bool
adcc::TensorImpl
::
is_element_allowed
(const std::vector<size_t> &tidx) const¶ Return whether the element referenced by tidx is allowed (non-zero) by the symmetry of the Tensor or not.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
adcc::TensorImpl
::
select_n_absmax
(size_t n, bool unique_by_symmetry) const¶ Get the n absolute largest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
adcc::TensorImpl
::
select_n_absmin
(size_t n, bool unique_by_symmetry) const¶ Get the n absolute smallest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
adcc::TensorImpl
::
select_n_max
(size_t n, bool unique_by_symmetry) const¶ Get the n largest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
adcc::TensorImpl
::
select_n_min
(size_t n, bool unique_by_symmetry) const¶ Get the n smallest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
void
adcc::TensorImpl
::
export_to
(scalar_type *memptr, size_t size) const¶ Extract the tensor to plain memory provided by the given pointer.
- Note
This will return a full, dense tensor. At least size elements of space are assumed at the provided memory location. The data is stored in row-major (C-like) format
-
void
adcc::TensorImpl
::
import_from
(const scalar_type *memptr, size_t size, scalar_type tolerance, bool symmetry_check)¶ Import the tensor from plain memory provided by the given pointer. The memory will be copied and all existing data overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
This function requires a full, dense tensor with the data stored in row-major (C-like) format.
- Parameters
memptr
: Full, dense memory pointer to the tensor data to be imported.size
: Size of the dense memory.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
virtual void
adcc::TensorImpl
::
import_from
(std::function<void(const std::vector<std::pair<size_t, size_t>>&, scalar_type *)> generator, scalar_type tolerance, bool symmetry_check, )¶ Import the tensor from a generator functor. All existing data will be overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
The generator is required to produce data in row-major (C-like) format at a designated memory location.
- Parameters
generator
: Generator functor. The functor is called with a list of ranges for each dimension. The ranges are half-open, left-inclusive and right-exclusive. The corresponding data should be written to the passed pointer into raw memory. This is an advanced functionality. Use only if you know what you are doing.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
std::string
adcc::TensorImpl
::
describe_symmetry
() const¶ Return a std::string providing hopefully helpful information about the symmetries stored inside the tensor object.
-
std::string
adcc::TensorImpl
::
describe_expression
(std::string stage = "unoptimised") const¶ Return a std::string providing hopefully helpful information about the expression tree stored inside the tensor object. Valid values for stage are “unoptimised”, “optimised”, “evaluation” returning the unoptimised expression tree as stored, an optimised form of it or the tree as used actually for evaluating the expression.
-
adcc::TensorImpl
::
operator libtensor::btensor<N, scalar_type>&
()¶ Convert object to btensor for use in libtensor functions.
-
std::shared_ptr<libtensor::btensor<N, scalar_type>>
adcc::TensorImpl
::
libtensor_ptr
()¶ Return inner btensor object
- Note
This is an advanced function. Use with care, since this can corrupt the internal state of the Tensor object.
-
std::shared_ptr<ExpressionTree>
adcc::TensorImpl
::
expression_ptr
() const¶ Return permutation, expression object and required keep-alives to this tensor
- Note
This is an advanced function. Use with care, since this can corrupt the internal state of the Tensor object.
Extractor function to convert the contained tensor from adcc::Tensor to an expression.
- Note
This is an internal function. Use only if you know what you are doing.
Extractor functions to convert the contained tensor of an adcc::Tensor object to an appropriate libtensor::btensor, The dimensionality N has to match
Extractor functions to convert the contained tensor of an adcc::Tensor object to an appropriate libtensor::btensor, The dimensionality N has to match Extractor function to convert the contained tensor of an adcc::Tensor object to an appropriate pointer to libtensor::btensor. The dimensionality N has to match.
-
template<size_t
N
>
classTensorImpl
: public adcc::Tensor¶ - #include <TensorImpl.hh>
Actual implementation of the Tensor class. For details about the functions see Tensor.hh
Public Functions
Construction of the tensor implementation class
- Note
This constructor is for experts only. Non-experts should use the make_tensor method instead.
-
std::shared_ptr<Tensor>
empty_like
() const Return a new tensor with the same dimensionality and symmetry as the passed tensor. The elements have undefined values.
-
std::shared_ptr<Tensor>
nosym_like
() const Return a new tensor with same dimensionality and shape (and bispace) but without any symmetry copied over
-
void
set_mask
(std::string mask, scalar_type value) Set a mask into a tensor to a specific value. The mask to set is defined by the mask string. Repetitive indices define the values to be set. E.g. for a 6D tensor the mask string “iijkli” would set all elements T_{iijkli} for all ijkl to the given value.
-
void
set_random
() Set the tensor to random data preserving symmetry
-
std::shared_ptr<Tensor>
scale
(scalar_type c) const Scale tensor by a scalar value and return the result
Add another tensor and return the result
Multiply another tensor elementwise and return the result
Divide another tensor elementwise and return the result
Add a linear combination to the represented tensor and store the result. Note that unlike
add
andscale
this operation is not lazy and is provided for optimising on cases where a lazy linear combination introduces a too large overhead.
-
std::shared_ptr<Tensor>
copy
() const Return a deep copy of this tensor.
-
std::shared_ptr<Tensor>
transpose
(std::vector<size_t> axes) const Return a transpose form of this tensor
- Parameters
axes
: New permutation of the dimensions of this tensor (e.g. (1,0,2,3) will permute dimension 0 and 1 and keep the others) If missing, just reverse the dimension order.
Compute the direct sum of this tensor with another tensor. All axes are used in the order of appearance (this and then other).
Return the tensordot of this tensor with another
- Parameters
axes
: Axes to contract over. The first vector refers to the axes of this tensor, the second vector to the axes of the other tensor.
Compute the Frobenius or l2 inner product with a list of other tensors, returning the results as a scalar array
-
std::shared_ptr<Tensor>
symmetrise
(const std::vector<std::vector<size_t>> &permutations) const Symmetrise with respect to the given index permutations by adding the elements resulting from appropriate index permutations.
Examples for permutations. Take a rank-4 tensor T_{ijkl} {{0,1}} Permute the first two indices, i.e. form 0.5 * (T_{ijkl} + T_{jikl}) {{0,1}, {2,3}} Form 0.5 * (T_{ijkl} + T_{jilk})
- Parameters
permutations
: The list of permutations to be applied simultaneously
- Note
Unlike the implementation in libtensor, this function includes the prefactor 0.5
-
std::shared_ptr<Tensor>
antisymmetrise
(const std::vector<std::vector<size_t>> &permutations) const Antisymmetrise with respect to the given index permutations and return the result. For details with respect to the format of the permutations, see symmetrise. In this case the output tensor will be antisymmetric with respect to these permutations.
- Note
Unlike the implementation in libtensor, this function includes the prefactor 0.5
-
double
trace
(std::string contraction) const Return the full trace of a tensor
- Parameters
contraction
: Indices to contract over using Einstein summation convention, e.g. “abab” traces over the 1st and 3rd and 2nd and 4th axis.
-
void
evaluate
() const Make sure to evaluate this tensor in case this has not yet happened
-
bool
needs_evaluation
() const Check weather the object represents an evaluated expression or not.
-
void
set_immutable
() Flag the tensor as immutable, allows some optimisations to be performed
-
bool
is_mutable
() const Is the tensor mutable
-
void
set_element
(const std::vector<size_t> &idx, scalar_type value) Set the value of a single tensor element
- Note
This is a slow function and should be avoided.
-
scalar_type
get_element
(const std::vector<size_t> &tidx) const Get the value of a single tensor element
- Note
This is a slow function and should be avoided.
-
bool
is_element_allowed
(const std::vector<size_t> &tidx) const Return whether the element referenced by tidx is allowed (non-zero) by the symmetry of the Tensor or not.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_absmax
(size_t n, bool unique_by_symmetry) const Get the n absolute largest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_absmin
(size_t n, bool unique_by_symmetry) const Get the n absolute smallest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_max
(size_t n, bool unique_by_symmetry) const Get the n largest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
std::vector<std::pair<std::vector<size_t>, scalar_type>>
select_n_min
(size_t n, bool unique_by_symmetry) const Get the n smallest elements along with their values
- Parameters
n
: Number of elements to selectunique_by_symmetry
: By default the returned elements are made unique by symmetry of the tensor. Setting this to false disables this feature.
-
void
export_to
(scalar_type *memptr, size_t size) const Extract the tensor to plain memory provided by the given pointer.
- Note
This will return a full, dense tensor. At least size elements of space are assumed at the provided memory location. The data is stored in row-major (C-like) format
-
void
import_from
(const scalar_type *memptr, size_t size, scalar_type tolerance, bool symmetry_check) Import the tensor from plain memory provided by the given pointer. The memory will be copied and all existing data overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
This function requires a full, dense tensor with the data stored in row-major (C-like) format.
- Parameters
memptr
: Full, dense memory pointer to the tensor data to be imported.size
: Size of the dense memory.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
virtual void
import_from
(std::function<void(const std::vector<std::pair<size_t, size_t>>&, scalar_type *)> generator, scalar_type tolerance, bool symmetry_check, ) Import the tensor from a generator functor. All existing data will be overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
The generator is required to produce data in row-major (C-like) format at a designated memory location.
- Parameters
generator
: Generator functor. The functor is called with a list of ranges for each dimension. The ranges are half-open, left-inclusive and right-exclusive. The corresponding data should be written to the passed pointer into raw memory. This is an advanced functionality. Use only if you know what you are doing.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
std::string
describe_symmetry
() const Return a std::string providing hopefully helpful information about the symmetries stored inside the tensor object.
-
std::string
describe_expression
(std::string stage = "unoptimised") const Return a std::string providing hopefully helpful information about the expression tree stored inside the tensor object. Valid values for stage are “unoptimised”, “optimised”, “evaluation” returning the unoptimised expression tree as stored, an optimised form of it or the tree as used actually for evaluating the expression.
-
operator libtensor::btensor<N, scalar_type>&
() Convert object to btensor for use in libtensor functions.
-
std::shared_ptr<libtensor::btensor<N, scalar_type>>
libtensor_ptr
() Return inner btensor object
- Note
This is an advanced function. Use with care, since this can corrupt the internal state of the Tensor object.
-
std::shared_ptr<ExpressionTree>
expression_ptr
() const Return permutation, expression object and required keep-alives to this tensor
- Note
This is an advanced function. Use with care, since this can corrupt the internal state of the Tensor object.
Compute the Frobenius or l2 inner product with a list of other tensors, returning the results as a scalar array
-
virtual void
export_to
(scalar_type *memptr, size_t size)¶ Extract the tensor to plain memory provided by the given pointer.
- Note
This will return a full, dense tensor. At least size elements of space are assumed at the provided memory location. The data is stored in row-major (C-like) format
-
virtual void
export_to
(std::vector<scalar_type> &output)¶ Extract the tensor into a std::vector, which will be resized to fit the data.
- Note
All data is stored in row-major (C-like) format
-
virtual void
import_from
(const scalar_type *memptr, size_t size, scalar_type tolerance = 0, bool symmetry_check = true) Import the tensor from plain memory provided by the given pointer. The memory will be copied and all existing data overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
This function requires a full, dense tensor with the data stored in row-major (C-like) format.
- Parameters
memptr
: Full, dense memory pointer to the tensor data to be imported.size
: Size of the dense memory.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
virtual void
import_from
(const std::vector<scalar_type> &input, scalar_type tolerance = 0, bool symmetry_check = true) Import the tensor from plain memory provided by the given vector. The memory will be copied and all existing data overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
This function requires a full, dense tensor with the data stored in row-major (C-like) format.
- Parameters
input
: Input data in a linearised vectortolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.
-
virtual void
import_from
(std::function<void(const std::vector<std::pair<size_t, size_t>>&, scalar_type *)> generator, scalar_type tolerance = 0, bool symmetry_check = true, ) Import the tensor from a generator functor. All existing data will be overwritten. If symmetry_check is true, the process will check that the data has the required symmetry to fit into the tensor. This requires a slower algorithm to be chosen.
- Note
The generator is required to produce data in row-major (C-like) format at a designated memory location.
- Parameters
generator
: Generator functor. The functor is called with a list of ranges for each dimension. The ranges are half-open, left-inclusive and right-exclusive. The corresponding data should be written to the passed pointer into raw memory. This is an advanced functionality. Use only if you know what you are doing.tolerance
: Threshold to account for numerical inconsistencies when checking the symmetry or for determining zero blocks.symmetry_check
: Should symmetry be explicitly checked during the import.