CrystalFp public interface. More...

#include <CrystalFp.h>

Public Member Functions
Constructor, destructor and structure reset
	CrystalFp (unsigned int aVerboseLevel)
	Constructor.

	~CrystalFp ()
	Destructor.

void	resetAll (void)
	Reset everything to the status just after the construction.

Available methods names
Names of the fingerprinting, distance and classification methods
const std::vector< std::string >	getFingerprintMethodsNames (void) const
	Return the names of the implemented fingerprint computation methods.

const std::vector< std::string >	getDistanceMethodsNames (void) const
	Return the names of the implemented distance computation methods.

const std::vector< std::string >	getGroupingMethodsNames (void) const
	Return the names of the implemented grouping methods.

Load phase methods
Load structures to be processed
void	addStructure (int aStep, unsigned int aNumAtoms, const float aCoords, const unsigned int aZ, const float *aUnitCell, bool aHasEnergy=false, float aEnergy=0.0F, bool aEnergyIsPerAtom=true)
	Load one new crystal structure optionally with an energy.

void	addStructureBatch (int aStep, unsigned int aNumAtoms, const float aCoords, const unsigned int aZ, const float *aUnitCell, bool aHasEnergy=false, float aEnergy=0.0F, bool aEnergyIsPerAtom=true)
	Load one new crystal structure optionally with an energy, but it does not update the selected structures list till addStructureBatchFinish() is called.

void	addStructureBatchFinish (void)
	Finish a batch loading.

size_t	getNumActiveStructures (void) const
	Return the number of structures loaded that will be used for the computational phases.

size_t	getNumTotalStructures (void) const
	Return the total number of structures loaded.

Select active structures methods
Select structures based on energies
void	energyThreshold (float aEnergyThreshold)
	Mark as active only the structures with energy less than the given value.

void	noEnergyThreshold (void)
	Mark as active all the loaded structures regardless of their energy.

Methods to access global quantities
Return quantities related to the full set of selected structures
bool	hasEnergies (void) const
	Test if all the loaded structures have an associated energy value.

float	getMinEnergy (void) const
	Get the minimum energy value between all the loaded structures.

bool	hasUnitCell (void) const
	Check if the structures have unit cell.

Methods to access structure quantities at given index
Return quantities related to the given structure
int	idxToStep (size_t aIdx) const
	Get the step number for the selected structure.

float	getTotalEnergy (size_t aIdx) const
	Get the total energy value for the selected structure.

float	getPerAtomEnergy (size_t aIdx) const
	Get the energy per atom value for the selected structure.

unsigned int	getNatoms (size_t aIdx) const
	Get the number of atoms for the selected structure.

const float *	getUnitCell (size_t aIdx) const
	Get the unit cell for the selected structure.

const unsigned int *	getAtomZ (size_t aIdx) const
	Get the kind of atoms for the selected structure.

const float *	getCoords (size_t aIdx) const
	Get the coordinates for the selected structure.

Compute fingerprints
Compute fingerprints for all the active structures
float	computeCutoffDistance (float aMargin=0.02F) const
	Return the suggested cutoff distance.

void	setFingerprintMethod (unsigned int aFingerprintType)
	Set the fingerprinting method to be used.

bool	isDiffractionLike (void) const
	Check if the method is "per element diffraction" and similar.

const std::string	getFingerprintMethod (void) const
	Get the description of the currently used fingerprinting method.

void	setCutoffDistance (float aCutoff)
	Set the cutoff distance to be used.

void	setNanoclusterStructureType (void)
	Modify the method for nanoclusters.

void	setDiffrBinSize (float aBinSize)
	Set diffraction bin width.

void	setDiffrPeakSize (float aPeakSize)
	Set the gaussian peak smoothing width.

void	forceFpLength (unsigned int aDim)
	Force the fingerprint dimensionality to the given value.

void	setCheckpointDir (const char *aDir)
	Set the checkpoint directory.

void	loadCheckpoint (void)
	Load the data contained in the checkpoint directory.

void	computeFingerprints (void)
	Compute the fingerprints.

unsigned int	getFingerprintNumSections (void) const
	Get the number of sections composing the fingerprint.

unsigned int	getFingerprintSectionLen (void) const
	The fingerprint section length.

bool	hasFingerprints (void) const
	Check if the fingerprints for the loaded structures have been computed.

float	getCutoffDistance (void) const
	Get the computed or set cutoff distance.

const float *	getFingerprint (size_t aStructureIdx) const
	Access the fingerprint for the selected structure.

float	getDiffrPeakSize (void) const
	Get the gaussian peak smoothing width.

float	getDiffrBinSize (void) const
	Get the bin width for diffraction like fingerprints smoothing.

const std::vector< std::vector < float > > &	getInteratomicDistances (unsigned int aIdx) const
	Return the interatomic distances from the given atom in the given structure.

const float *	getWeights (size_t aIdx) const
	Get the weights for the selected structure.

Compute distances
Compute distances between fingerprints
void	setDistanceMethod (unsigned int aMeasureType)
	Set the distance measure to be used.

const std::string	getDistanceMethod (void) const
	Get the description of the currently used distance measure.

void	computeDistanceMatrix (void)
	Compute distances between all fingerprints.

bool	hasDistanceMatrix (void) const
	Check if the distances for the loaded structures have been computed.

float	getDistance (size_t aIdx1, size_t aIdx2) const
	Returns the distance between two structures.

float	getMaxDistance (void) const
	Get the maximum distance between two fingerprints.

Classify structures methods
Classify structures into groups
void	setGroupingMethod (unsigned int aGroupingMethod)
	Set the grouping method to be used.

const std::string	getGroupingMethod (void) const
	Get the description of the currently used grouping method.

void	groupResults (void)
	Do the grouping.

void	setMaxGroupingDistance (float aMaxDistance)
	Set the distance threshold for grouping.

float	getMaxGroupingDistance (void) const
	Get the distance threshold for grouping.

void	setK (unsigned int aK)
	Set the common neighbors count.

unsigned int	getNgroups (void) const
	Return the number of groups found.

const std::vector< std::set < unsigned int > > &	getGroups (void) const
	Return the list of groups found.

unsigned int	getNsingle (void) const
	Return the number of ungrouped entries found.

bool	groupingNeedsK (void) const
	Test if the grouping method selected needs K parameter.

unsigned int	reduceDuplicatesToRepresentative (std::vector< unsigned int > &aNewIndexList)
	Remove grouped structures leaving only one representative structure.

Serialize/unserialize class
Serialize/unserialize class
void	serialize (std::ofstream &aStream) const
	Serialize the class to the given binary stream.

void	unserialize (std::ifstream &aStream, bool aAppend=false, int aStepOffset=10000)
	Unserialize the class from the given binary stream.

Debugging support
Class debugging support
void	dump (void) const
	Dump the CrystalFp internal structures to help library debugging.

Detailed Description

CrystalFp public interface.

Author: Mario Valle - Swiss National Supercomputing Centre (CSCS)

Date: 2008-06-06 (initial version); 2009-09-01 (version 1.0)

Version: 1.0

Definition at line 29 of file CrystalFp.h.

Constructor & Destructor Documentation

cfp::CrystalFp::CrystalFp ( unsigned int aVerboseLevel )

Constructor.

Parameters

aVerboseLevel

Set the verbosity level of the library

0: No messages
1: Moderate
2: Something more
3: Trace all the structure operations (which step is processed)

cfp::CrystalFp::~CrystalFp ( )

Destructor.

Member Function Documentation

void cfp::CrystalFp::addStructure	(	int	aStep,
		unsigned int	aNumAtoms,
		const float *	aCoords,
		const unsigned int *	aZ,
		const float *	aUnitCell,
		bool	aHasEnergy = `false`,
		float	aEnergy = `0.0F`,
		bool	aEnergyIsPerAtom = `true`
	)

Load one new crystal structure optionally with an energy.

Parameters

aStep	A numeric identifier of the structure
aNumAtoms	Number of atoms of the structure to be loaded
aCoords	The coordinates of the atoms. The array contains contiguous x1, y1, z1, x2, y2, z2, ...
aZ	The Z value of the corresponding atom
aUnitCell	The unit cell given as a vector[16]: [0..2] a; [4..6] b; [8..10] c; [12..14] origin; [15] set to 1.0 and the rest set to 0.0
aHasEnergy	If true, the structure has associated energy
aEnergy	The internal energy or enthalpy of the structure
aEnergyIsPerAtom	If true the energy is per atom and not per structure

void cfp::CrystalFp::addStructureBatch	(	int	aStep,
		unsigned int	aNumAtoms,
		const float *	aCoords,
		const unsigned int *	aZ,
		const float *	aUnitCell,
		bool	aHasEnergy = `false`,
		float	aEnergy = `0.0F`,
		bool	aEnergyIsPerAtom = `true`
	)

Load one new crystal structure optionally with an energy, but it does not update the selected structures list till addStructureBatchFinish() is called.

After a set of AddStructureBatch() calls have been made, the AddStructureBatchFinish() call should be issued.

Parameters

aStep	A numeric identifier of the structure
aNumAtoms	Number of atoms of the structure to be loaded
aCoords	The coordinates of the atoms. The array contains contiguous x1, y1, z1, x2, y2, z2, ...
aZ	The Z value of the corresponding atom
aUnitCell	The unit cell given as a vector[16]: [0..2] a; [4..6] b; [8..10] c; [12..14] origin; [15] set to 1.0 and the rest set to 0.0
aHasEnergy	If true, the structure has associated energy
aEnergy	The internal energy or enthalpy of the structure
aEnergyIsPerAtom	If true the energy is per atom and not per structure

void cfp::CrystalFp::addStructureBatchFinish ( void )

Finish a batch loading.

float cfp::CrystalFp::computeCutoffDistance ( float aMargin = 0.02F ) const

Return the suggested cutoff distance.

Parameters

aMargin The percentage to increase the cutoff distance to avoid border cases (default 2%)

Returns: The suggested cutoff distance

void cfp::CrystalFp::computeDistanceMatrix ( void )

Compute distances between all fingerprints.

Exceptions

CrystalFpFatal If fingerprints has been not computed before.

void cfp::CrystalFp::computeFingerprints ( void )

Compute the fingerprints.

void cfp::CrystalFp::dump ( void ) const

Dump the CrystalFp internal structures to help library debugging.

void cfp::CrystalFp::energyThreshold ( float aEnergyThreshold )

Mark as active only the structures with energy less than the given value.

Parameters

aEnergyThreshold The threshold energy value

void cfp::CrystalFp::forceFpLength ( unsigned int aDim )

Force the fingerprint dimensionality to the given value.

Parameters

aDim	The forced dimensionality value

const unsigned int* cfp::CrystalFp::getAtomZ ( size_t aIdx ) const

Get the kind of atoms for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The array of atom's types

const float* cfp::CrystalFp::getCoords ( size_t aIdx ) const

Get the coordinates for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The coordinates array

float cfp::CrystalFp::getCutoffDistance ( void ) const

Get the computed or set cutoff distance.

Returns: The cutoff distance or zero if not set

float cfp::CrystalFp::getDiffrBinSize ( void ) const

Get the bin width for diffraction like fingerprints smoothing.

Returns: The diffraction bin size

float cfp::CrystalFp::getDiffrPeakSize ( void ) const

Get the gaussian peak smoothing width.

Returns: The gaussian peak width used (could be zero)

float cfp::CrystalFp::getDistance	(	size_t	aIdx1,
		size_t	aIdx2
	)		const

Returns the distance between two structures.

Parameters

aIdx1	Index of the first structure
aIdx2	Index of the second structure

Returns: The distance between the two structures

Exceptions

CrystalFpFatal On invalid indices.

const std::string cfp::CrystalFp::getDistanceMethod ( void ) const

Get the description of the currently used distance measure.

Returns: The description

const std::vector<std::string> cfp::CrystalFp::getDistanceMethodsNames ( void ) const

Return the names of the implemented distance computation methods.

Returns: The list of distance measure methods names

const float* cfp::CrystalFp::getFingerprint ( size_t aStructureIdx ) const

Access the fingerprint for the selected structure.

Parameters

aStructureIdx Index of the structure

Returns: The fingerprint (length is num_sections * section_length)

const std::string cfp::CrystalFp::getFingerprintMethod ( void ) const

Get the description of the currently used fingerprinting method.

Returns: The description

const std::vector<std::string> cfp::CrystalFp::getFingerprintMethodsNames ( void ) const

Return the names of the implemented fingerprint computation methods.

Returns: The vector of fingerprinting methods names

unsigned int cfp::CrystalFp::getFingerprintNumSections ( void ) const

Get the number of sections composing the fingerprint.

Returns: The number of sections

unsigned int cfp::CrystalFp::getFingerprintSectionLen ( void ) const

The fingerprint section length.

Returns: The length of one fingerprint section

const std::string cfp::CrystalFp::getGroupingMethod ( void ) const

Get the description of the currently used grouping method.

Returns: The description

const std::vector<std::string> cfp::CrystalFp::getGroupingMethodsNames ( void ) const

Return the names of the implemented grouping methods.

Returns: The list of grouping method names

const std::vector< std::set<unsigned int> >& cfp::CrystalFp::getGroups ( void ) const

Return the list of groups found.

Returns: Array of groups each represented as array of the index of the structures in this group

const std::vector< std::vector<float> >& cfp::CrystalFp::getInteratomicDistances ( unsigned int aIdx ) const

Return the interatomic distances from the given atom in the given structure.

Parameters

aIdx	Index of the structure

Returns: Vector (one for each atom) of vector of distances to all other atoms in the extended unit cell

float cfp::CrystalFp::getMaxDistance ( void ) const

Get the maximum distance between two fingerprints.

Returns: The maximum distance

float cfp::CrystalFp::getMaxGroupingDistance ( void ) const

Get the distance threshold for grouping.

Returns: The threshold distance

float cfp::CrystalFp::getMinEnergy ( void ) const

Get the minimum energy value between all the loaded structures.

Returns: The minimum energy value

unsigned int cfp::CrystalFp::getNatoms ( size_t aIdx ) const

Get the number of atoms for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The number of atoms

unsigned int cfp::CrystalFp::getNgroups ( void ) const

Return the number of groups found.

Returns: The number of groups found

unsigned int cfp::CrystalFp::getNsingle ( void ) const

Return the number of ungrouped entries found.

Returns: The number of ungrouped entries (called single) found

size_t cfp::CrystalFp::getNumActiveStructures ( void ) const

Return the number of structures loaded that will be used for the computational phases.

Returns: The number of active structures

size_t cfp::CrystalFp::getNumTotalStructures ( void ) const

Return the total number of structures loaded.

Returns: The number of loaded structures (active and ignored)

float cfp::CrystalFp::getPerAtomEnergy ( size_t aIdx ) const

Get the energy per atom value for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The energy value

float cfp::CrystalFp::getTotalEnergy ( size_t aIdx ) const

Get the total energy value for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The energy value

const float* cfp::CrystalFp::getUnitCell ( size_t aIdx ) const

Get the unit cell for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The unit cell

const float* cfp::CrystalFp::getWeights ( size_t aIdx ) const

Get the weights for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The weights (one for each fingerprint part)

bool cfp::CrystalFp::groupingNeedsK ( void ) const

Test if the grouping method selected needs K parameter.

Returns: True if K needed

void cfp::CrystalFp::groupResults ( void )

Do the grouping.

Exceptions

CrystalFpFatal If distances has not been computed before.

bool cfp::CrystalFp::hasDistanceMatrix ( void ) const

Check if the distances for the loaded structures have been computed.

Returns: True if the distance matrix has been computed

bool cfp::CrystalFp::hasEnergies ( void ) const

Test if all the loaded structures have an associated energy value.

Returns: True if all the loaded structures have an associated energy value

bool cfp::CrystalFp::hasFingerprints ( void ) const

Check if the fingerprints for the loaded structures have been computed.

Returns: True if all fingerprints have been computed (or loaded from checkpoint dir)

bool cfp::CrystalFp::hasUnitCell ( void ) const

Check if the structures have unit cell.

Returns: True if all structures have unit cell

int cfp::CrystalFp::idxToStep ( size_t aIdx ) const

Get the step number for the selected structure.

Parameters

aIdx	Index of the structure

Returns: The step number

bool cfp::CrystalFp::isDiffractionLike ( void ) const

Check if the method is "per element diffraction" and similar.

Returns: True if the selected method is diffraction like

void cfp::CrystalFp::loadCheckpoint ( void )

Load the data contained in the checkpoint directory.

void cfp::CrystalFp::noEnergyThreshold ( void )

Mark as active all the loaded structures regardless of their energy.

unsigned int cfp::CrystalFp::reduceDuplicatesToRepresentative ( std::vector< unsigned int > & aNewIndexList )

Remove grouped structures leaving only one representative structure.

Parameters

[out] aNewIndexList The routine fills the given array with the original indices of the new, reduced, set of structures

Returns: The new number of active structures or zero if nothing has been done

void cfp::CrystalFp::resetAll ( void )

Reset everything to the status just after the construction.

void cfp::CrystalFp::serialize ( std::ofstream & aStream ) const

Serialize the class to the given binary stream.

Parameters

[in] aStream The stream to which the class will be serialized

Exceptions

CrystalFpFatal On write error.

void cfp::CrystalFp::setCheckpointDir ( const char * aDir )

Set the checkpoint directory.

In this directory one file is created for each fingerprint.

Parameters

aDir	The directory path

void cfp::CrystalFp::setCutoffDistance ( float aCutoff )

Set the cutoff distance to be used.

Parameters

aCutoff The cutoff distance to use

void cfp::CrystalFp::setDiffrBinSize ( float aBinSize )

Set diffraction bin width.

Parameters

aBinSize The diffraction bin size

void cfp::CrystalFp::setDiffrPeakSize ( float aPeakSize )

Set the gaussian peak smoothing width.

Parameters

aPeakSize The gaussian peak width to be used (if zero the peak is not smoothed)

void cfp::CrystalFp::setDistanceMethod ( unsigned int aMeasureType )

Set the distance measure to be used.

Parameters

aMeasureType The kind of distance measure (index in the list of names)

Exceptions

CrystalFpFatal If aMeasureType is invalid

void cfp::CrystalFp::setFingerprintMethod ( unsigned int aFingerprintType )

Set the fingerprinting method to be used.

Parameters

aFingerprintType The kind of fingerprint to compute (index in the list of names)

Exceptions

CrystalFpFatal If aFingerprintType is invalid

void cfp::CrystalFp::setGroupingMethod ( unsigned int aGroupingMethod )

Set the grouping method to be used.

Parameters

aGroupingMethod The kind of grouping method (index in the list of names)

Exceptions

CrystalFpFatal If aGroupingMethod is invalid

void cfp::CrystalFp::setK ( unsigned int aK )

Set the common neighbors count.

It is used by some grouping methods

Parameters

aK	The common neighbors count

void cfp::CrystalFp::setMaxGroupingDistance ( float aMaxDistance )

Set the distance threshold for grouping.

Parameters

aMaxDistance The threshold distance

void cfp::CrystalFp::setNanoclusterStructureType ( void )

Modify the method for nanoclusters.

If this function is called, the unit cell is ignored

void cfp::CrystalFp::unserialize	(	std::ifstream &	aStream,
		bool	aAppend = `false`,
		int	aStepOffset = `10000`
	)

Unserialize the class from the given binary stream.

Parameters

[in]	aStream	The stream from which the class should be deserialized
[in]	aAppend	Append the read structures to the list of already read structures
[in]	aStepOffset	Apply this offset to the id of the appended structures

Exceptions

CrystalFpFatal On read error and on format validation error.

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

CrystalFp.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation