Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   Related Pages  

ObjCryst::Crystal Class Reference

Crystal class: Unit cell, spacegroup, scatterers. More...

#include <Crystal.h>

Inheritance diagram for ObjCryst::Crystal::

ObjCryst::RefinableObj List of all members.

Public Methods

 Crystal ()
 Default Constructor.

 Crystal (const double a, const double b, const double c, const string &SpaceGroupId)
 Crystal Constructor (orthorombic). More...

 Crystal (const double a, const double b, const double c, const double alpha, const double beta, const double gamma, const string &SpaceGroupId)
 Crystal Constructor (triclinic). More...

 Crystal (const Crystal &oldCryst)
 Crystal copy constructor.

 ~Crystal ()
 Crystal destructor.

virtual const string GetClassName () const
 Name for this class ("RefinableObj", "Crystal",...). This is only useful to distinguish different classes when picking up objects from the RefinableObj Global Registry.

void AddScatterer (Scatterer *scatt)
 Add a scatterer to the crystal. More...

void RemoveScatterer (Scatterer *scatt)
 Remove a Scatterer. This also deletes the scatterer.

long GetNbScatterer () const
 Number of scatterers in the crystal.

ScattererGetScatt (const string &scattName)
 Provides an access to the scatterers. More...

const ScattererGetScatt (const string &scattName) const
 Provides a const access to the scatterers. More...

ScattererGetScatt (const long scattIndex)
 Provides an access to the scatterers. More...

const ScattererGetScatt (const long scattIndex) const
 Provides a const access to the scatterers. More...

ObjRegistry< Scatterer > & GetScattererRegistry ()
 Get the registry of scatterers.

ObjRegistry< ScatteringPower > & GetScatteringPowerRegistry ()
 Get the registry of ScatteringPower included in this Crystal.

const ObjRegistry< ScatteringPower > & GetScatteringPowerRegistry () const
 Get the registry of ScatteringPower included in this Crystal.

void AddScatteringPower (ScatteringPower *scattPow)
 Add a ScatteringPower for this Crystal. It must be allocated in the heap, and not used by any other Crystal.

void RemoveScatteringPower (ScatteringPower *scattPow)
 Remove a ScatteringPower for this Crystal. (the Scattering power is deleted). This function should check that it is not used any more before removing it.

ScatteringPowerGetScatteringPower (const string &name)
 Find a ScatteringPower from its name. Names must be unique in a given Crystal.

virtual const ScatteringComponentListGetScatteringComponentList () const
 Get the list of all scattering components. More...

CrystVector_double GetLatticePar () const
 Lattice parameters (a,b,c,alpha,beta,gamma) as a 6-element vector in Angstroems and radians.

double GetLatticePar (const int whichPar) const
 Return one of the 6 Lattice parameters, 0<= whichPar <6 (a,b,c,alpha,beta,gamma), returned in Angstroems and radians.

const CrystMatrix_double & GetBMatrix () const
 Get the 'B' matrix (Crystal::mBMatrix)for the crystal (orthogonalization matrix for the given lattice, in the reciprocal space). More...

CrystVector_double GetOrthonormalCoords (const double x, const double y, const double z) const
 Get orthonormal cartesian coordinates for a set of (x,y,z) fractional coordinates. More...

void FractionalToOrthonormalCoords (double &x, double &y, double &z) const
 Get orthonormal cartesian coordinates for a set of (x,y,z) fractional coordinates. More...

void OrthonormalToFractionalCoords (double &x, double &y, double &z) const
 Get fractional cartesian coordinates for a set of (x,y,z) orthonormal coordinates. More...

void Print (ostream &os=cout) const
 Prints some info about the crystal
Parameters:
os  the stream to which the information is outputed (default=cout).
More...


const SpaceGroupGetSpaceGroup () const
 Access to the crystal SpaceGroup object.

SpaceGroupGetSpaceGroup ()
 Access to the crystal SpaceGroup object.

CrystMatrix_double GetMinDistanceTable (const double minDistance=0.1) const
 Minimum interatomic distance between all scattering components (atoms) in the crystal. More...

void PrintMinDistanceTable (const double minDistance=0.1, ostream &os=cout) const
 Print the minimum distance table between all scattering centers (atoms) in the crystal. More...

ostream & POVRayDescription (ostream &os, bool onlyIndependentAtoms=false) const
 XMLOutput POV-Ray Description for this Crystal. More...

virtual void GLInitDisplayList (const bool onlyIndependentAtoms=false, const double xMin=-.1, const double xMax=1.1, const double yMin=-.1, const double yMax=1.1, const double zMin=-.1, const double zMax=1.1) const
 Create an OpenGL DisplayList of the crystal. More...

void CalcDynPopCorr (const double overlapDist=1., const double mergeDist=.0) const
 Compute the 'Dynamical population correction for all atoms. Atoms which are considered "equivalent" (ie currently with the same Z number) and which are overlapping see their Dynamical occupancy changed so that when they fully overlap, they are equivalent to 1 atom. More...

void ResetDynPopCorr () const
 Reset Dynamical Population Correction factors (ie set it to 1).

void SetUseDynPopCorr (const int use)
 Set the use of dynamical population correction (Crystal::mUseDynPopCorr). More...

double GetBumpMergeCostFunction () const
 Get the Anti-bumping/pro-Merging cost function. More...

void SetBumpMergeDistance (const ScatteringPower &scatt1, const ScatteringPower &scatt2, const double dist=1.5)
 Set the Anti-bumping distance between two scattering types.

void SetBumpMergeDistance (const ScatteringPower &scatt1, const ScatteringPower &scatt2, const double dist, const bool allowMerge)
 Set the Anti-bumping distance between two scattering types.

const RefinableObjClockGetClockLatticePar () const
 When were lattice parameters last changed ?

const RefinableObjClockGetClockScattererList () const
 When was the list of scatterers last changed ?

unsigned int GetNbCostFunction () const
 Number of Cost functions.

const string & GetCostFunctionName (const unsigned int) const
 Get a Cost function name from its id#.

const string & GetCostFunctionDescription (const unsigned int) const
 Get the (short) description of a cost function.

virtual double GetCostFunctionValue (const unsigned int)
 Get the current value of a cost function this should be const...

virtual void XMLOutput (ostream &os, int indent=0) const
 Output to stream in well-formed XML. More...

virtual void XMLInput (istream &is, const XMLCrystTag &tag)
 Input From stream. More...

virtual void GlobalOptRandomMove (const double mutationAmplitude)
 Make a random move of the current configuration. More...

virtual void CIFOutput (ostream &os) const
 output Crystal structure as a cif file (EXPERIMENTAL !). More...


Private Methods

void Init (const double a, const double b, const double c, const double alpha, const double beta, const double gamma, const string &SpaceGroupId, const string &name)
 Init all Crystal parameters. More...

int FindScatterer (const string &scattName) const
 Find a scatterer (its index # in mpScatterrer[]) with a given name
Warning:
There should be no duplicate names !!! :TODO: test in AddScatterer().


void InitMatrices () const
 \internal.Init the (de)orthogonalization matrices. They are re-computed only if parameters have changed since last call.

void UpdateLatticePar ()
  Update cell parameters for tetragonal, trigonal, hexagonal, cubic lattices. Also set angular parameters for those group which need it. This is needed during Refinement, since for example in a quadratic spg, only a is refined and we need to have b=a...

void InitRefParList ()
 Prepare the refinable parameters list. More...

void CalcDistTable (const bool fast, const double asymUnitMargin=4) const
 Compute the distance Table (mDistTable) for all scattering components. More...


Private Attributes

CrystVector_double mCellDim
 a,b and c in Angstroems, angles (stored) in radians For cubic, rhomboedric crystals, only the 'a' parameter is relevant. For quadratic and hexagonal crystals, only a and c parameters are relevant. The MUTABLE is temporary ! It should not be !

SpaceGroup mSpaceGroup
 The space group of the crystal.

ObjRegistry< ScatterermScattererRegistry
 The registry of scatterers for this crystal.

CrystMatrix_double mBMatrix
 B Matrix (Orthogonalization matrix for reciprocal space)

. More...

CrystMatrix_double mOrthMatrix
 Eucl Matrix (Orthogonalization matrix for direct space)

. More...

CrystMatrix_double mOrthMatrixInvert
 inverse of Eucl Matrix (de-orthogonalization matrix for direct space).

CrystMatrix_double mDistTableSq
 Distance table (squared) between all scattering components in the crystal. More...

CrystVector_long mDistTableIndex
 Index of scattering components for the Distance table. More...

ScatteringComponentList mScattCompList
 The list of all scattering components in the crystal.

RefinableObjClock mLatticeClock
 Clock for lattice paramaters.

RefObjOpt mUseDynPopCorr
 Use Dynamical population correction (ScatteringComponent::mDynPopCorr) during Structure factor calculation ?

CrystMatrix_double mBumpDistanceMatrix
 Matrix of "bumping" (squared) distances.

CrystMatrix_bool mAllowMerge
 Allow merging of atoms in the bump/merge function(should be true for identical atoms)?

ObjRegistry< ScatteringPowermScatteringPowerRegistry
 The registry of ScatteringPower for this Crystal.

RefinableObjClock mClockScattererList
 Last time the list of Scatterers was changed.

RefinableObjClock mClockLatticePar
 Last time lattice parameters were changed.

RefinableObjClock mClockMetricMatrix
  Last time metric matrices were computed.

RefinableObjClock mClockScattCompList
  Last time the ScatteringComponentList was generated.

RefinableObjClock mClockNeighborTable
  Last time the Neighbor Table was generated.

RefinableObjClock mClockLatticeParUpdate
  Last time the lattice parameters whre updated.

RefinableObjClock mClockDynPopCorr
  Last time the dynamical population correction was computed.


Detailed Description

Crystal class: Unit cell, spacegroup, scatterers.

A Crystal object has several main characteristics : (1) a unit cell, (2) a Spacegroup and (3) a list of Scatterer. Also stored in the Crystal is a list of the ScttaringPower used by all the scatterers of this crystal.

The crystal is capable of giving a list of all scattering components (ie the list of all unique scattering 'points' (ScatteringComponent, ie atoms) in the unit cell, each associated to a ScatteringPower).

When those scattering components are on a special position or overlapping with another component of the same type, it is possible to correct dynamically the occupancy of this/these components to effectively have only one component instead of several due to the overlapping. This method is interesting for global optimization where atoms must not be "locked" on a special position. If this "Dynamical Occupancy Correction" is used then no occupancy should be corrected for special positions, since this will be done dynamically.

A crystal structure can be viewed in 3D using OpenGL.

Todo:
exporting (and importing) crystal structures to/from other files format than ObjCryst's XML (eg CIF, and format used by refinement software)

Currently only 3D crystal structures can be handled, with no magnetic structure (that may be done later) and no incommensurate structure.


Constructor & Destructor Documentation

Crystal const double    a,
const double    b,
const double    c,
const string &    SpaceGroupId
 

Crystal Constructor (orthorombic).

Parameters:
a,b,c  : unit cell dimension, in angstroems
SpaceGroupId:  space group symbol or number

Crystal const double    a,
const double    b,
const double    c,
const double    alpha,
const double    beta,
const double    gamma,
const string &    SpaceGroupId
 

Crystal Constructor (triclinic).

Parameters:
a,b,c  : unit cell dimension, in angstroems
alpha,beta,gamma  : unit cell angles, in radians.
SpaceGroupId:  space group symbol or number


Member Function Documentation

void AddScatterer Scatterer   scatt
 

Add a scatterer to the crystal.

Warning:
the scatterer must be allocated in the heap, since the scatterer will not be copied but used directly. A Scatterer can only belong to one Crystal. It will be detroyed when removed or when the Crystal is destroyed.
Parameters:
scatt  : the address of the scatterer to be included in the crystal scatterer names must be unique in a given crystal.
Note:
that the ScatteringPower used in the Scatterer should be one of the Crystal (see Crystal::AddScatteringPower())

virtual void CIFOutput ostream &    os const [virtual]
 

output Crystal structure as a cif file (EXPERIMENTAL !).

Warning:
This is very crude and EXPERIMENTAL so far: only isotropic scattering power are supported, and there is not much information beside atom positions...

void CalcDistTable const bool    fast,
const double    asymUnitMargin = 4
const [private]
 

Compute the distance Table (mDistTable) for all scattering components.

\internal

Parameters:
fast  : if true, the distance calculations will be made using integers, thus with a lower precision but faster. Less atoms will also be involved (using the AsymmetricUnit) to make it even faster.
asymUnitMargin  (in Angstroem). This is used only if fast=true. In that case, the distance is calculated between (i) independent atoms in the asymmetric unit cell and (ii) all atoms which are inside the asymmetric unit cell or less than 'asymUnitMargin' distant from the asymmetric unit borders. This parameter should be used when only the shortest distances need to be calculated (typically for dynamical population correction). Using a too short margin will result in having some distances calculated wrongly (ie one atom1 in the unit cell could have an atom2 neighbor just outside the sym unit: if margin=0, then the distance is calculated between atom1 and the atom2 symmetric inside the asym unit).
Warning:
Crystal::GetScatteringComponentList() must be called beforehand, since this will not be done here.

Bug:
(possible bug). Is the distance computed in "fast" mode the same under Windows and Linux ?

Returns:
see Crystal::mDistTableSq and Crystal::mDistTableIndex
Todo:
sanitize the result distance table in a more usable structure than the currently used Crystal::mDistTableSq and Crystal::mDistTableIndex.

optimize again. Test if recomputation is needed using Clocks. Use a global option instead of asymUnitMargin.

Warning:
not using the fast option has not been very much tested...

void CalcDynPopCorr const double    overlapDist = 1.,
const double    mergeDist = .0
const
 

Compute the 'Dynamical population correction for all atoms. Atoms which are considered "equivalent" (ie currently with the same Z number) and which are overlapping see their Dynamical occupancy changed so that when they fully overlap, they are equivalent to 1 atom.

Parameters:
overlapDist  : distance below which atoms (ScatteringComponents, to be more precise) are considered overlapping and should be corrected. The correction changes the dynamical occupancy from 1 to 1/nbAtomOverlapping, progressively as the distance falls from overlapDist to mergeDist.
mergeDist  : distance below which atoms are considered fully overlapping. If 3 atoms are 'fully' overlapping, then all have a dynamical population correction equal to 1/3
This is const since ScatteringComponent::mDynPopCorr is mutable.

\warning. Do not call this function, which will turn private. This is called by only Crystal::GetScatteringComponentList()

void FractionalToOrthonormalCoords double &    x,
double &    y,
double &    z
const
 

Get orthonormal cartesian coordinates for a set of (x,y,z) fractional coordinates.

X,y and z input are changed to Amgstroems values The convention is taken following : e1 is chosen along a, e2 in the (a,b) plane, then e3 is along c*

virtual void GLInitDisplayList const bool    onlyIndependentAtoms = false,
const double    xMin = -.1,
const double    xMax = 1.1,
const double    yMin = -.1,
const double    yMax = 1.1,
const double    zMin = -.1,
const double    zMax = 1.1
const [virtual]
 

Create an OpenGL DisplayList of the crystal.

Parameters:
onlyIndependentAtoms  if false (the default), then all symmetrics are displayed within the given limits \ param xMin,xMax,yMin,yMax,zMin,zMax: in fractionnal coordinates, the region in which we want scaterrers to be displayed. The test is made on the center of the scatterer (eg a ZScatterer (molecule) will not be 'cut' on the border).

const CrystMatrix_double& GetBMatrix   const
 

Get the 'B' matrix (Crystal::mBMatrix)for the crystal (orthogonalization matrix for the given lattice, in the reciprocal space).

The convention is taken following Giacovazzo, "Fundamentals of Crystallography", p.69 "e1 is chosen along a*, e2 in the (a*,b*) plane, then e3 is along c".

double GetBumpMergeCostFunction   const
 

Get the Anti-bumping/pro-Merging cost function.

Only works (ie returnes a non-null value) if you have added antibump distances using Crystal::SetBumpMergeDistance().

Bug:
(?) The value of this function is not the same under Windows and Linux (??). Probably due to the optimization used (ie we are using a "fast" calculation of distances, which uses integers...)

CrystMatrix_double GetMinDistanceTable const double    minDistance = 0.1 const
 

Minimum interatomic distance between all scattering components (atoms) in the crystal.

This will return a symmetrical matrix with NbComp rows and cols, where NbComp is the number of independent scattering components in the unit cell. All distances are given in Angstroems.

Note that the distance of a given atom with 'itself' is not generally equal to 0 (except full special position), but equal to the min distance with its symmetrics.

Parameters:
minDistance  : atoms who are less distant than (minDistance,in Angstroems) are considered equivalent. So the smallest distance between any atoms will be at least minDistance.

CrystVector_double GetOrthonormalCoords const double    x,
const double    y,
const double    z
const
 

Get orthonormal cartesian coordinates for a set of (x,y,z) fractional coordinates.

Results are given in Amgstroems. The convention is taken following : e1 is chosen along a, e2 in the (a,b) plane, then e3 is along c*

const Scatterer& GetScatt const long    scattIndex const
 

Provides a const access to the scatterers.

Parameters:
scattIndex  the number of the scatterer to access

Scatterer& GetScatt const long    scattIndex
 

Provides an access to the scatterers.

Parameters:
scattIndex  the number of the scatterer to access

const Scatterer& GetScatt const string &    scattName const
 

Provides a const access to the scatterers.

Parameters:
scattName  the name of the scatterer to access

Scatterer& GetScatt const string &    scattName
 

Provides an access to the scatterers.

Parameters:
scattName  the name of the scatterer to access

virtual const ScatteringComponentList& GetScatteringComponentList   const [virtual]
 

Get the list of all scattering components.

Parameters:
useDynPopCorr:  if true, then the dynamical polpulation correction will be computed and stored in the list for each component. Else the dynamical occupancy correction will be set to 1 for all components.

virtual void GlobalOptRandomMove const double    mutationAmplitude [virtual]
 

Make a random move of the current configuration.

This is for global optimization algorithms. the moves for each parameter are less than their global optimization step, multiplied by the mutation amplitude.

\warning: this makes a random move for the parameter declared for this object, and it is the duty of the object to decide whether the included objects should be moved and how. (eg an algorithm should only call for a move with the top object, and this object decides how he and his sub-objects moves). By default (RefinableObj implementation) all included objects are moved recursively.

RefinableObj::

Parameters:
mutationAmplitude:  multiplier for the maximum move amplitude, for all parameters

Reimplemented from ObjCryst::RefinableObj.

void Init const double    a,
const double    b,
const double    c,
const double    alpha,
const double    beta,
const double    gamma,
const string &    SpaceGroupId,
const string &    name
[private]
 

Init all Crystal parameters.

Parameters:
a,b,c  : unit cell dimension, in angstroems
alpha,beta,gamma  : unit cell angles
SpcGroup:  space group number (1..230)
name:  name for the crystal, : '(TaSe4)2I'

void InitRefParList   [private]
 

Prepare the refinable parameters list.

This is called once when creating the crystal. OBSOLETE ?

void OrthonormalToFractionalCoords double &    x,
double &    y,
double &    z
const
 

Get fractional cartesian coordinates for a set of (x,y,z) orthonormal coordinates.

Result is stored into x,y and z The convention is taken following : e1 is chosen along a, e2 in the (a,b) plane, then e3 is along c*

ostream& POVRayDescription ostream &    os,
bool    onlyIndependentAtoms = false
const
 

XMLOutput POV-Ray Description for this Crystal.

Parameters:
onlyIndependentAtoms  if false, all symmetrics are showed in the drawing.
Warning:
This currently needs some fixing (ZScatterer does not work ?) Use rather the OpenGL 3D display which is more useful.
Parameters:
os  the stream to which the information is outputed (default=cout)

void Print ostream &    os = cout const
 

Prints some info about the crystal

Parameters:
os  the stream to which the information is outputed (default=cout).

Todo:
one function to print on one line and a PrintLong() function

void PrintMinDistanceTable const double    minDistance = 0.1,
ostream &    os = cout
const
 

Print the minimum distance table between all scattering centers (atoms) in the crystal.

Parameters:
os  the stream to which the information is outputed (default=cout)

void SetUseDynPopCorr const int    use
 

Set the use of dynamical population correction (Crystal::mUseDynPopCorr).

Atoms which are considered "equivalent" (ie currently with the same Z number) and which are overlapping see their Dynamical occupancy changed so that when they fully overlap, they are equivalent to 1 atom.

The Dynamical Occupancy correction will be performed in Crystal::GetScatteringComponentList() automatically.

This seriously affects the speed of the calculation, since computing interatomic distances is lenghty.

Parameters:
use  set to 1 to use, 0 not to use it.

virtual void XMLInput istream &    is,
const XMLCrystTag   tag
[virtual]
 

Input From stream.

Todo:
Add an bool XMLInputTag(is,tag) function to recognize all the tags from the stream. So that each inherited class can use the XMLInputTag function from its parent (ie take advantage of inheritance). The children class would first try to interpret the tag, then if unsuccessful would pass it to its parent (thus allowing overloading), etc...

Reimplemented from ObjCryst::RefinableObj.

virtual void XMLOutput ostream &    os,
int    indent = 0
const [virtual]
 

Output to stream in well-formed XML.

Todo:
Use inheritance.. as for XMLInputTag()...

Reimplemented from ObjCryst::RefinableObj.


Member Data Documentation

CrystMatrix_double mBMatrix [private]
 

B Matrix (Orthogonalization matrix for reciprocal space)

.

Note:
this matrix is and must remain upper triangular. this is assumed for some optimizations.

CrystVector_long mDistTableIndex [private]
 

Index of scattering components for the Distance table.

These are the index of the scattering components corresponding to each row in Crystal::mDistTableSq.

CrystMatrix_double mDistTableSq [private]
 

Distance table (squared) between all scattering components in the crystal.

Matrix, in Angstroems^2 (the square root is not computed for optimization purposes), with as many columns as there are components in Crystal::mScattCompList, and as many rows as necessary (to include symmetrics in and nearby the Asymmetric Unit). See Crystal::CalcDistTable()

The order of columns follows the order in Crystal::mScattCompList. The order of rows is given in Crystal::mDistTableIndex

CrystMatrix_double mOrthMatrix [private]
 

Eucl Matrix (Orthogonalization matrix for direct space)

.

Note:
this matrix is and must remain upper triangular. this is assumed for some optimizations.


The documentation for this class was generated from the following file:
Generated on Wed Nov 14 19:48:37 2001 for ObjCryst++ by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001