Track the energy components of a collection of systems in an HPC-capable array. This object uses the familiar trick of defining an enumerator (StateVariables) with a final entry to indicate its total length, so that if more energy components need to be tracked in the future the storage and indexing can automatically adjust with new entries. More...

#include <scorecard.h>

Public Member Functions
	ScoreCard (int system_count_in, int capacity_in=16, int nrg_scale_bits_in=default_energy_scale_bits)
	The constructor requires only the number of systems.

int	getSystemCount () const
	Get the number of systems that this object is tracking.

int	getSampleSize () const
	Get the number of steps that have been sampled.

int	getDataStride () const
	Get the stride used to store separate results for each system in the instantaneous accumulator arrays.

int	getSampleCapacity () const
	Get the sample capacity (the number of individual energy measurements that the object is prepared to store).

int	getEnergyScaleBits () const
	Get the number of bits of fixed precision to which results are stored.

int	getTimeStep (int time_index) const
	Get the time step at which a particular energy value was taken.

void	reserve (int new_capacity)
	Reserve space for storing sampled energy component values.

void	contribute (StateVariable var, llint amount, int system_index=0)
	Place a result into one of the instantaneous state variable accumulators. This is for CPU activity; on the GPU, the contributions will occur as part of each energy kernel using pointers. This will automatically update running accumulators for statistical tracking. It is add + commit, below.

void	add (StateVariable var, llint amount, int system_index=0)
	Add a result to a growing total in one of the instantaneous state variable accumulators. This is for CPU activity; on the GPU, the contributions will occur as part of each energy kernel using pointers.

void	computePotentialEnergy (HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)
	Compute total potential energies for all systems in the instantaneous accumulators as well as all time series accumulators. This total is not automatically computed by various interaction evaluations, which only compute individual "components" of this quantity.

void	computeTotalEnergy (HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)
	Compute total energies for all systems in the instantaneous accumulators as well as all time series accumulators. This total is not automatically computed by various interaction evaluations, which only compute individual "components" of this quantity.

void	incrementSampleCount ()
	Increment the number of sampled steps. This will automatically allocate additional capacity if the sampled step count reaches the object's capacity.

void	resetSampleCount (int count_in=0)
	Reset the sample counter (this is implicitly done by initialize() if that function is called to operate on all start variables and all systems, on either the host or HPC device).

const ScoreCard *	getSelfPointer () const
	Get a const pointer to this object.

void	setLastTimeStep (int time_index, HybridTargetLevel tier=HybridTargetLevel::HOST)
	Set the time index for the most recent stored set of energies.


	ScoreCard (const ScoreCard &original)=default
	Copy and move constructors help make the energy tracker a first-class C++ object. The defaults apply as there are no const member variables and no POINTER-kind Hybrid objects.

	ScoreCard (ScoreCard &&original)=default


ScoreCard &	operator= (const ScoreCard &other)=default
	Copy and move assignment operators complete the support for integrating this energy tracker with Standard Template Library mechanics. The defaults apply as there are no const member variables and no POINTER-kind Hybrid objects.

ScoreCard &	operator= (ScoreCard &&other)=default


template<typename T>
T	getEnergyScalingFactor () const
	Get the energy scaling factors in single- or double-precision floating point format.

template<typename T>
T	getInverseEnergyScalingFactor () const


const ScoreCardReader	data (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the appropriate abstract based on the const-ness of the abstract.

ScoreCardWriter	data (HybridTargetLevel tier=HybridTargetLevel::HOST)


void	initialize (StateVariable var, int system_index=0, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)
	Initialize some or all instantaneous state variable accumulators. If all state variable accumulators are initialized in all systems, the sample counter will also be reset.

void	initialize (const std::vector< StateVariable > &var, int system_index=0, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)

void	initialize (int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)

void	initialize (HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)


void	commit (StateVariable var, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)
	Commit the (assumed complete) accumulated results in one or more state variables to the running tallies and time series kept for statistical purposes.

void	commit (const std::vector< StateVariable > &var, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)

void	commit (StateVariable var, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)

void	commit (const std::vector< StateVariable > &var, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)

void	commit (int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)

void	commit (HybridTargetLevel tier=HybridTargetLevel::HOST, const GpuDetails &gpu=null_gpu)


std::vector< double >	reportPotentialEnergies (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Report the total energy, or total potential energy, for one system or for all systems. Each result will be summed in the internal fixed-point accumulation before conversion to real values in units of kcal/mol.

double	reportPotentialEnergy (int system_index=0, HybridTargetLevel tier=HybridTargetLevel::HOST) const

std::vector< double >	reportTotalEnergies (HybridTargetLevel tier=HybridTargetLevel::HOST) const

double	reportTotalEnergy (int system_index=0, HybridTargetLevel tier=HybridTargetLevel::HOST) const


std::vector< double >	reportInstantaneousStates (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Report instantaneous results in kcal/mol, as a double-precision vector.

std::vector< double >	reportInstantaneousStates (int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const

std::vector< double >	reportInstantaneousStates (StateVariable aspect, HybridTargetLevel tier=HybridTargetLevel::HOST) const

double	reportInstantaneousStates (StateVariable aspect, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const


std::vector< double >	reportAverageStates (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Report averaged results in kcal/mol, as a double-precision vector.

std::vector< double >	reportAverageStates (int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const

std::vector< double >	reportAverageStates (StateVariable aspect, HybridTargetLevel tier=HybridTargetLevel::HOST) const

double	reportAverageStates (StateVariable aspect, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const


std::vector< double >	reportVarianceOfStates (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Report standard deviations in kcal/mol, as a double-precision vector.

std::vector< double >	reportVarianceOfStates (int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const

std::vector< double >	reportVarianceOfStates (StateVariable aspect, HybridTargetLevel tier=HybridTargetLevel::HOST) const

double	reportVarianceOfStates (StateVariable aspect, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const


std::vector< double >	reportHistory (int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Report the energy history for one or more systems.

std::vector< double >	reportHistory (StateVariable aspect, int system_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const

std::vector< double2 >	reportHistory (HybridTargetLevel tier=HybridTargetLevel::HOST) const

std::vector< double2 >	reportHistory (StateVariable aspect, HybridTargetLevel tier=HybridTargetLevel::HOST) const


void	importCard (const ScoreCard *other, size_t fill_index, size_t source_index)
	Import the results of another ScoreCard into this one, including all components and the associated energy history. If the current object does not have sufficient space either in terms of systems or sample capacity (depth of history), it will be re-allocated. This functionality is available on the GPU as a free function energyCopy(), which allows the reader from the source and the writer from the destination to be used rather than a long series of pointers and array size constants.

void	importCard (const ScoreCard &other, size_t fill_index, size_t source_index)

void	importCard (const ScoreCard *other, const std::vector< int > &fill_indices, const std::vector< int > &source_indices)

void	importCard (const ScoreCard &other, const std::vector< int > &fill_indices, const std::vector< int > &source_indices)

Detailed Description

Track the energy components of a collection of systems in an HPC-capable array. This object uses the familiar trick of defining an enumerator (StateVariables) with a final entry to indicate its total length, so that if more energy components need to be tracked in the future the storage and indexing can automatically adjust with new entries.

Constructor & Destructor Documentation

◆ ScoreCard() [1/2]

stormm::energy::ScoreCard::ScoreCard	(	int	system_count_in,
		int	capacity_in = 16,
		int	nrg_scale_bits_in = default_energy_scale_bits )

The constructor requires only the number of systems.

Parameters

system_count_in	The number of systems to track
capacity_in	The capacity (samples per energy component in each system) to initially allocate for
nrg_scale_bits_in	Number of bits after the decimal with which to store energy values

◆ ScoreCard() [2/2]

stormm::energy::ScoreCard::ScoreCard ( const ScoreCard & original )

default

Copy and move constructors help make the energy tracker a first-class C++ object. The defaults apply as there are no const member variables and no POINTER-kind Hybrid objects.

Parameters

original The original energy tracking object to build from

Member Function Documentation

◆ add()

void stormm::energy::ScoreCard::add	(	StateVariable	var,
		llint	amount,
		int	system_index = 0 )

Add a result to a growing total in one of the instantaneous state variable accumulators. This is for CPU activity; on the GPU, the contributions will occur as part of each energy kernel using pointers.

Parameters

var	The state variable to which this contribution belongs, i.e. bond energy
amount	Amount to contribute to said state variable (in fixed precision format)
system_index	Index of the system (among a list of those being tracked) that the contrbution describes

◆ commit()

void stormm::energy::ScoreCard::commit	(	StateVariable	var,
		int	system_index,
		HybridTargetLevel	tier = HybridTargetLevel::HOST,
		const GpuDetails &	gpu = null_gpu )

Commit the (assumed complete) accumulated results in one or more state variables to the running tallies and time series kept for statistical purposes.

Overloaded:

Commit results for a single state variable
Commit results for a list of specific state variables
Commit results for all state variables
Commit results for a single system, or for all systems

Parameters

var	The state variable to which this contribution belongs, i.e. bond energy
system_index	Index of the system (among a list of those being tracked) that the contrbution describes

◆ computePotentialEnergy()

void stormm::energy::ScoreCard::computePotentialEnergy	(	HybridTargetLevel	tier = HybridTargetLevel::HOST,
		const GpuDetails &	gpu = null_gpu )

Compute total potential energies for all systems in the instantaneous accumulators as well as all time series accumulators. This total is not automatically computed by various interaction evaluations, which only compute individual "components" of this quantity.

Parameters

tier	Perform this operation on the CPU host or GPU device

◆ computeTotalEnergy()

void stormm::energy::ScoreCard::computeTotalEnergy	(	HybridTargetLevel	tier = HybridTargetLevel::HOST,
		const GpuDetails &	gpu = null_gpu )

Compute total energies for all systems in the instantaneous accumulators as well as all time series accumulators. This total is not automatically computed by various interaction evaluations, which only compute individual "components" of this quantity.

Parameters

tier	Perform this operation on the CPU host or GPU device

◆ contribute()

void stormm::energy::ScoreCard::contribute	(	StateVariable	var,
		llint	amount,
		int	system_index = 0 )

Place a result into one of the instantaneous state variable accumulators. This is for CPU activity; on the GPU, the contributions will occur as part of each energy kernel using pointers. This will automatically update running accumulators for statistical tracking. It is add + commit, below.

Parameters

var	The state variable to which this contribution belongs, i.e. bond energy
amount	Amount to contribute to said state variable (in fixed precision format)
system_index	Index of the system (among a list of those being tracked) that the contrbution describes

◆ data()

const ScoreCardReader stormm::energy::ScoreCard::data ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Get the appropriate abstract based on the const-ness of the abstract.

Parameters

tier	Get pointers to data on the host or on the HPC accelerator device

◆ getTimeStep()

int stormm::energy::ScoreCard::getTimeStep ( int time_index ) const

Get the time step at which a particular energy value was taken.

Parameters

time_index The index of the energies and time step number in question

◆ importCard()

void stormm::energy::ScoreCard::importCard	(	const ScoreCard *	other,
		size_t	fill_index,
		size_t	source_index )

Import the results of another ScoreCard into this one, including all components and the associated energy history. If the current object does not have sufficient space either in terms of systems or sample capacity (depth of history), it will be re-allocated. This functionality is available on the GPU as a free function energyCopy(), which allows the reader from the source and the writer from the destination to be used rather than a long series of pointers and array size constants.

Overloaded:

Supply a const pointer or const reference to the other energy tracking object
Import a single system into a specific index.
Import multiple systems into multiple indices.

Parameters

other	The other energy tracking object
fill_index	System index of the current object to import results into
fill_indices	System indices of the current object to import results into
source_index	System index of the original object to import results from
source_indices	System indices of the original object to import results from

◆ initialize()

void stormm::energy::ScoreCard::initialize	(	StateVariable	var,
		int	system_index = 0,
		HybridTargetLevel	tier = HybridTargetLevel::HOST,
		const GpuDetails &	gpu = null_gpu )

Initialize some or all instantaneous state variable accumulators. If all state variable accumulators are initialized in all systems, the sample counter will also be reset.

Overloaded:

Initialize a single state variable accumulator
Initialize a list of state variable accumulators
Initialize all state variable accumulators in one or more systems

Parameters

var	The state variable to initialize
system_index	Index of the system (among a list of those being tracked) that the contrbution describes
tier	Indicate whether to initialize accumulators on the host or device
gpu	Details of the HPC device in use

◆ operator=()

ScoreCard & stormm::energy::ScoreCard::operator= ( const ScoreCard & other )

default

Copy and move assignment operators complete the support for integrating this energy tracker with Standard Template Library mechanics. The defaults apply as there are no const member variables and no POINTER-kind Hybrid objects.

Parameters

other Object to which the present ScoreCard shall be equated

◆ reportAverageStates()

std::vector< double > stormm::energy::ScoreCard::reportAverageStates ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Report averaged results in kcal/mol, as a double-precision vector.

Overloaded:

Report results for all systems (the vector will be concatenated, with padding removed)
Report results for a single system
Report a specific result for all systems
Report a specific result for a single system

Parameters

system_index	Index of the system of interest within all of those being tracked
aspect	The type of energy or virial quantity of interest
tier	Level from which to extract the data

◆ reportHistory()

std::vector< double > stormm::energy::ScoreCard::reportHistory	(	int	system_index,
		HybridTargetLevel	tier = HybridTargetLevel::HOST ) const

Report the energy history for one or more systems.

Overloaded:

Report the total energy history, as recorded on either the host or GPU device
Report the history of a specific energy component
Report results for a specific system or as the mean and standard deviation (in the x and y components of a double2 tuple) of all systems

Parameters

system_index	Index of the system of interest within all of those being tracked
aspect	The type of energy or virial quantity of interest (if none is specified the history of systems' total energy will be reported, taking elements from all potential and kinetic energy sources)
tier	Level from which to extract the data

◆ reportInstantaneousStates()

std::vector< double > stormm::energy::ScoreCard::reportInstantaneousStates ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Report instantaneous results in kcal/mol, as a double-precision vector.

Overloaded:

Report results for all systems (the vector will be concatenated, with padding removed)
Report results for a single system
Report a specific result for all systems
Report a specific result for a single system

Parameters

system_index	Index of the system of interest within all of those being tracked
aspect	The type of energy or virial quantity of interest
tier	Level from which to extract the data

◆ reportPotentialEnergies()

std::vector< double > stormm::energy::ScoreCard::reportPotentialEnergies ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Report the total energy, or total potential energy, for one system or for all systems. Each result will be summed in the internal fixed-point accumulation before conversion to real values in units of kcal/mol.

Overloaded:

Sum the total or potential energies of a selected system
Sum the total or potential energies of all systems

Parameters

system_index	Index of the system of interest
tier	Level from which to extract the data

◆ reportVarianceOfStates()

std::vector< double > stormm::energy::ScoreCard::reportVarianceOfStates ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Report standard deviations in kcal/mol, as a double-precision vector.

Overloaded:

Report results for all systems (the vector will be concatenated, with padding removed)
Report results for a single system
Report a specific result for all systems
Report a specific result for a single system

Parameters

system_index	Index of the system of interest within all of those being tracked
aspect	The type of energy or virial quantity of interest
tier	Level from which to extract the data

◆ reserve()

void stormm::energy::ScoreCard::reserve ( int new_capacity )

Reserve space for storing sampled energy component values.

Parameters

new_capacity The new capacity to allocate for

◆ resetSampleCount()

void stormm::energy::ScoreCard::resetSampleCount ( int count_in = 0 )

Reset the sample counter (this is implicitly done by initialize() if that function is called to operate on all start variables and all systems, on either the host or HPC device).

Parameters

count_in The number of samples to set the object as having (default 0, full reset)

◆ setLastTimeStep()

void stormm::energy::ScoreCard::setLastTimeStep	(	int	time_index,
		HybridTargetLevel	tier = HybridTargetLevel::HOST )

Set the time index for the most recent stored set of energies.

Parameters

time_index	Set the time index
tier	The memory level at which to set the time step

The documentation for this class was generated from the following files:

src/Potential/scorecard.h
src/Potential/scorecard.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ScoreCard() [1/2]

◆ ScoreCard() [2/2]

Member Function Documentation

◆ add()

◆ commit()

◆ computePotentialEnergy()

◆ computeTotalEnergy()

◆ contribute()

◆ data()

◆ getTimeStep()

◆ importCard()

◆ initialize()

◆ operator=()

◆ reportAverageStates()

◆ reportHistory()

◆ reportInstantaneousStates()

◆ reportPotentialEnergies()

◆ reportVarianceOfStates()

◆ reserve()

◆ resetSampleCount()

◆ setLastTimeStep()