class Atoms

Overview

The main list of atoms class. More…

#include <Atoms.h>
 
class Atoms {
public:
    // construction
 
    Atoms(const Vec* p, int n, SuperCell* s);
    virtual ~Atoms();
 
    // methods
 
    virtual SuperCell* GetSuperCell() const;
    virtual const Vec* GetUnitCell() const;
    virtual void SetUnitCell(const Vec newbasis[3], bool fix);
    virtual void SetCalculator(AsapPotential* potential);
    AsapPotential* GetPotential() const;
    void MarkChanged();
    int GetChangeCounter() const;
    virtual void SetCartesianPositions(const Vec* p);
    virtual void GetCartesianPositions(Vec* p) const;
    virtual const Vec* GetCartesianPositions() const;
    Vec* GetPositionsPtr();
    virtual void GetUnwrappedPositions(vector<Vec>& p) const;
    virtual void SetUnwrappedPositions(const Vec* p);
    virtual void NormalizeDifferences(Vec* diff) const;
    virtual void NormalizeDifference(Vec& diff) const;
    virtual void NormalizePositions();
    virtual void NormalizePosition(Vec& pos) const;
    virtual void NormalizePosition(Vec& pos, Vec& scaled_translation) const;
    virtual void ReNormalizePosition(Vec& pos, Vec& scaled_translation) const;
    virtual void SetAtomicNumbers(const int* z);
    virtual const int* GetAtomicNumbers() const;
    int* GetAtomicNumbersPtr();
    virtual void GetListOfElements(set<int>& elements) const;
    void SetNumberOfImages(int i);
    int GetNumberOfImages() const;
    virtual int GetNumberOfAtoms() const;
    int GetNumberOfRealAtoms() const;
    virtual void SetNumberOfAtoms(int n);
};

Detailed Documentation

The main list of atoms class.

The Atoms class stores the coordinates and atomic numbers of the atoms. Coordinates are stored as Cartesian coordinates. Atoms has a reference to a SuperCell object containing the unitcell of the simulation, and a pointer to a Potential object responsible of force calculations. Other information about atoms (such as velocities and forces) are not stored in the C++ code but live in Python.

Construction

Atoms(const Vec* p, int n, SuperCell* s)

Construct Atoms from array of positions, number of elements and a SuperCell.

virtual ~Atoms()

Deletes the atoms. Does not delete Potential or SuperCell.

Methods

virtual SuperCell* GetSuperCell() const

Return a pointer to the SuperCell object.

virtual const Vec* GetUnitCell() const

Return the unitcell vectors.

virtual void SetUnitCell(const Vec newbasis[3], bool fix)

Set a new unit cell, rescaling the positions unless fix is true.

virtual void SetCalculator(AsapPotential* potential)

Set a Potential. An eventual old Potential is not deallocated.

AsapPotential* GetPotential() const

Get a pointer to the Potential.

void MarkChanged()

Update the change pointer.

The change counter is updated whenever the atoms are changed. It is used to decide if e.g. forces should be recalculated. Methods such as SetCartesianPositions() increment the counter.

int GetChangeCounter() const

Get the change counter.

virtual void SetCartesianPositions(const Vec* p)

Set the Cartesian positions.

Warning

When atoms.SetCartesianPositions() is called from Python, that is translated into a call to SetUwrappedPositions(), not to a call to this method.

The cartesian positions are copied from the array of 3-vectors (Vec) to the internal array. No length checks are done.

virtual void GetCartesianPositions(Vec* p) const

Return a copy of the Cartesian positions.

This version returns all degrees of freedom, i.e. both atoms and nodes in a quasicontinuum simulation. It does not return ghost atoms.

Warning

When atoms.GetCartesianPositions() is called from Python, that is translated into a call to GetUwrappedPositions(), not to a call to this method.

virtual const Vec* GetCartesianPositions() const

Return a const pointer to the Cartesian positions.

This version returns a pointer to the coordinates of all atoms. If ghost atoms are present, they are at the end of the array. It is up to the caller to know if ghost atoms are present, and to access them (or not) according to the need. Non-atomistic degrees of freedom, such as nodes in QC simulations, are not returned by this version.

Bug The difference in semantics between the two versions of GetCartesianPositions is most unfortunate: one of them should be renamed.

Vec* GetPositionsPtr()

Return a non-const pointer to the Cartesian positions. DANGEROUS!

GetPositionsPtr returns a pointer allowing modification of the positions. Be sure to call MarkChanged if this is done.

virtual void GetUnwrappedPositions(vector<Vec>& p) const

Return the positions, hiding that they may have been wrapped due to the boundary conditions.

This is the function used by Python when GetCartesianPositions is called.

virtual void SetUnwrappedPositions(const Vec* p)

Set the positions from an array of positions not taking any wrapping into account.

The already existing offset (caused by wrapping through periodic boundaries) is applied to the atoms. This is the function used by Python when SetCartesianPositions is called.

virtual void NormalizeDifferences(Vec* diff) const

Apply periodic boundary conditions to differences in positions.

Normalize an array of vectors containing differences in positions using periodic boundary conditions and the minimum image convention. If there are free boundary conditions in a specific direction, nothing is done to that coordinate of the vectors.

virtual void NormalizeDifference(Vec& diff) const

Apply periodic boundary conditions to difference in positions.

virtual void NormalizePositions()

Apply periodic boundary conditions to the positions. Does NOT call MarkChanged !

Normalize the positions, i.e. translate the atoms back into the supercell if there are periodic boundary conditions. This does not count as changing the atoms, so the change counter is NOT updated. The actual work is done by the SuperCell. This method should be called by the Potential, which may (should?) delegate it to the NeighborList.

virtual void NormalizePosition(Vec& pos) const

Normalize a position which is not owned by the atoms.

If another object holds a position needing to be normalized, this function should be called. It exists in two versions, one just normalizing the position, and one also returning the scaled space correction applied.

virtual void NormalizePosition(Vec& pos, Vec& scaled_translation) const

Normalize a position which is not owned by the atoms.

This version of the call reports the translation in scaled_translation, so the same translation can be obtained later (by calling ReNormalizePosition) without redoing the decision on whether to wrap. This is useful if positions need to be normalized between neighborlist updates, and is currently used by the Quasicontinuum code.

virtual void ReNormalizePosition(Vec& pos, Vec& scaled_translation) const

Repeat a normalization. See NormalizePosition(a,b).

virtual void SetAtomicNumbers(const int* z)

Set the atomic numbers. Should be done right after construction.

virtual const int* GetAtomicNumbers() const

Return a const pointer to the atomic numbers.

int* GetAtomicNumbersPtr()

Return a non-const pointer to the atomic numbers. DANGEROUS!

GetAtomicNumbersPtr returns a pointer allowing modification of the atomic numbers. Use with care, and call MarkChanged manually!

virtual void GetListOfElements(set<int>& elements) const

Get a set of all elements present in the simulations.

void SetNumberOfImages(int i)

Set the number of images. Used by the neighbor list.

int GetNumberOfImages() const

Get the number of images. Used by the neighbor list.

virtual int GetNumberOfAtoms() const

Get the number of atoms (including nodes in a QC simulation).

In a QuasiContinuum calculation we have real atoms and node atoms. GetNumberOfAtoms() is a virtual function: For a QCAtoms class it will return the number of real atoms plus the number of node atoms. This number is needed by SWIG to get the size of arrays. The method GetNumberOfRealAtoms() is needed by potentials and the Neighbor List object (they only deal with the real atoms).

int GetNumberOfRealAtoms() const

Get the number of atoms (excluding nodes in a QC simulation).

See also the documentation of GetNumberOfAtoms().

virtual void SetNumberOfAtoms(int n)

Change the number of atoms.

Change the number of atoms, and resize the arrays containing the data. If the number of atoms is increased, the end of the arrays will contain garbage. Call both SetCartesianPositions() and SetAtomicNumbers() after calling this method, and remember to update any relevent Python arrays. Mainly for use by ParallelAtoms when the atoms migrate between processors.