---

ObjCryst::RefinableObj Class Reference

Generic Refinable Object. More...

#include <RefinableObj.h>

Inheritance diagram for ObjCryst::RefinableObj::

List of all members.

Public Methods
	RefinableObj ()
	Constructor.
	RefinableObj (const bool internalUseOnly)
	Constructor. Using internalUseOnly=true will avoid registering the the object to any registry, and thus (for example) no display will be created, nor will this object be automatically be saved.
	RefinableObj (const RefinableObj &old)
	Defined not implemented... Should never be called (copying the refinable parameters would allow you to modify the input object). Use the default constructor and RefinableObj::AddPar(RefinableObj&) instead.
virtual	~RefinableObj ()
	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.
virtual const string &	GetName () const
	Name of the object.
virtual void	SetName (const string &name)
	Name of the object.
void	operator= (const RefinableObj &old)
	Defined not implemented... More...
void	PrepareForRefinement () const
	Find which parameters are used and not fixed, for a refinement /optimization. This must be called before any refinement...
void	FixAllPar ()
	Fix All parameters.
void	UnFixAllPar ()
	UnFix All parameters.
void	SetParIsFixed (const long parIndex, const bool fix)
	Fix/un-fix one parameter from its #.
void	SetParIsFixed (const string &parName, const bool fix)
	Fix/un-fix one parameter from its name.
void	SetParIsFixed (const RefParType *type, const bool fix)
	Fix/un-fix one family of parameters.
void	SetParIsUsed (const string &parName, const bool use)
	Set whether a parameter is used.
void	SetParIsUsed (const RefParType *type, const bool use)
	Set whether a family of parameters is used.
long	GetNbPar () const
	Total number of refinable parameter in the object. Note that some may be actually fixed or even not used !! For refinement use PrepareForRefinement(), NbRefParNotFixed(), and ParNotFixed(i).
long	GetNbParNotFixed () const
	Total number of non-fixed parameters. Is initialized by PrepareForRefinement().
RefinablePar &	GetPar (const long i)
	Access all parameters in the order they were inputted.
const RefinablePar &	GetPar (const long i) const
	Access all parameters in the order they were inputted.
RefinablePar &	GetPar (const string &name)
	Access all parameters from their name.
const RefinablePar &	GetPar (const string &name) const
	Access all parameters from their name.
RefinablePar &	GetPar (const REAL *)
	Access parameter from its adress.
const RefinablePar &	GetPar (const REAL *) const
	Access parameter from its adress.
RefinablePar &	GetParNotFixed (const long i)
	Access all parameters in the order they were inputted, skipping fixed parameters. Must call PrepareForRefinement() before !
const RefinablePar &	GetParNotFixed (const long i) const
	Access all parameters in the order they were inputed, skipping fixed parameters. Must call PrepareForRefinement() before !
void	AddPar (const RefinablePar &newRefPar)
	Add a refinable parameter. More...
void	AddPar (RefinablePar *newRefPar)
	Add a refinable parameter. More...
void	AddPar (RefinableObj &newRefParList)
	Add all the parameters in another RefinableObj. More...
virtual void	Print () const
long	CreateParamSet (const string name="") const
	Save the current set of refined values in a new set. More...
void	SaveParamSet (const long id) const
	Save the current set of refined values over a previously-created set of saved values. More...
void	RestoreParamSet (const long id)
	Restore a saved set of values. More...
const CrystVector_REAL &	GetParamSet (const long setId) const
	Access one save refpar set. More...
CrystVector_REAL &	GetParamSet (const long setId)
	Access one save refpar set. More...
REAL	GetParamSet_ParNotFixedHumanValue (const long setId, const long parNumber) const
	Access the (human) value of one refined parameter in a saved set of parameters. More...
const void	EraseAllParamSet ()
	Erase all saved refpar sets.
void	SetLimitsAbsolute (const string &parName, const REAL min, const REAL max)
	Change the limits for a given parameter, giving absolute new limits.
void	SetLimitsAbsolute (const RefParType *type, const REAL min, const REAL max)
	Change the limits for a category of parameters, giving absolute new limits.
void	SetLimitsRelative (const string &parName, const REAL min, const REAL max)
	Change the limits for a given parameter, giving relative new limits (eg giving -.1 and +.1 will set new limits at the current value + min and current value + max) Thus min should logically be <0 and max >0.
void	SetLimitsRelative (const RefParType *type, const REAL min, const REAL max)
	Change the limits for a category of parameters, giving relative new limits (eg giving -.1 and +.1 will set new limits at the current value + min and current value + max). Thus min should logically be <0 and max >0.
void	SetLimitsProportional (const string &parName, const REAL min, const REAL max)
	Change the limits for a given parameter, proportionnaly to the current value. min should be < 1. and max > 1.
void	SetLimitsProportional (const RefParType *type, const REAL min, const REAL max)
	Change the limits for a category of parameters, proportionnaly to their current value. min should be < 1. and max > 1.
void	SetGlobalOptimStep (const RefParType *type, const REAL step)
	Change the maximum step to use during Global Optimization algorithms.
ObjRegistry< RefinableObj > &	GetSubObjRegistry ()
	Access to the registry of RefinableObj used by this object.
const ObjRegistry< RefinableObj > &	GetSubObjRegistry () const
	Access to the registry of RefinableObj used by this object.
virtual void	RegisterClient (RefinableObj &) const
	Register a new object using this object. More...
virtual void	DeRegisterClient (RefinableObj &) const
	Deregister an object (which not any more) using this object.
bool	IsBeingRefined () const
	Is the object being refined ? (Can be refined by one algorithm at a time only.).
virtual void	BeginOptimization (const bool allowApproximations=false, const bool enableRestraints=false)
	This should be called by any optimization class at the begining of an optimization. More...
virtual void	EndOptimization ()
	This should be called by any optimization class at the end of an optimization. More...
virtual void	RandomizeConfiguration ()
	Randomize Configuration (before a global optimization). This Affects only parameters which are limited and not fixed. The randomization also affects all sub-objects (recursive).
virtual void	GlobalOptRandomMove (const REAL mutationAmplitude)
	Make a random move of the current configuration. More...
void	BeginGlobalOptRandomMove ()
	Raise a flag, to be sure not to make a random change more than once in each RefinableObj. More...
virtual unsigned int	GetNbCostFunction () const
	Number of Cost functions.
virtual const string &	GetCostFunctionName (const unsigned int) const
	Get a Cost function name from its id#.
virtual const string &	GetCostFunctionDescription (const unsigned int) const
	Get the (short) description of a cost function.
virtual REAL	GetCostFunctionValue (const unsigned int)
	Get the current value of a cost function this should be const...
virtual unsigned int	GetNbLSQFunction () const
	Number of LSQ functions.
virtual const CrystVector_REAL &	GetLSQCalc (const unsigned int) const
	Get the current calculated value for the LSQ function.
virtual const CrystVector_REAL &	GetLSQObs (const unsigned int) const
	Get the observed values for the LSQ function.
virtual const CrystVector_REAL &	GetLSQWeight (const unsigned int) const
	Get the weight values for the LSQ function.
void	ResetParList ()
	Re-init the list of refinable parameters, removing all parameters. This does not delete the RefinablePar if RefinableObj::mDeleteRefParInDestructor is false.
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	UpdateDisplay () const
	If there is an interface, this should be automatically be called each time there is a 'new, significant' configuration to report.
unsigned int	GetNbOption () const
	Number of Options for this object.
RefObjOpt &	GetOption (const unsigned int i)
	Access to the options.
const RefObjOpt &	GetOption (const unsigned int i) const
	const access to the options.
virtual void	GetGeneGroup (const RefinableObj &obj, CrystVector_uint &groupIndex, unsigned int &firstGroup) const
	Get the gene group assigned to each parameter. More...
void	SetDeleteRefParInDestructor (const bool b)
	Set this object not to delete its list of parameters when destroyed. More...
const RefinableObjClock &	GetRefParListClock () const
	What was the last time a RefinablePar was added/removed ?
virtual REAL	GetRestraintCost () const
	Get the restraint cost (penalty). More...
void	AddRestraint (Restraint *pNewRestraint)
	Add a new restraint.
Protected Methods
long	FindPar (const string &name) const
	Find a refinable parameter with a given name.
long	FindPar (const REAL *) const
	Find a refinable parameter from the adress of its value.
void	AddSubRefObj (RefinableObj &)
	Add an object in the registry of used objects. More...
void	RemoveSubRefObj (RefinableObj &)
	Remove an object in the registry of used objects. More...
void	InitRandomSeedFromTime () const
	Init the seed for random number generation from current time. More...
void	AddOption (RefObjOpt *opt)
	Add an option for this parameter. More...
virtual void	Prepare ()
	Prepare everything (if necessary) for an optimization/calculation. More...
Protected Attributes
string	mName
	Name for this RefinableObject. Should be unique, at least in the same scope.+.
RefinablePar **	mpRefPar
	Array of pointers to the refinable parameters.
long	mNbRefPar
	Number of refinable parameters.
long	mMaxNbRefPar
	Maximum number of refinable parameters (array size-dynamically allocated).
Restraint **	mpRestraint
	Array of pointers to the restraints for this object. This excludes all RefinableP.ar declared in RefinableObj::mpRefPar, which can also be restrained.
long	mNbRestraint
	Number of refinable parameters (not including possible RefinablePar which are also restrained).
long	mMaxNbRestraint
	Maximum number of restraints (dynamically allocated).
CrystVector_REAL **	mpSavedValuesSet
	Array of pointers to arrays used to save sets of values for all parameters.
string **	mpSavedValuesSetName
	Names associated to the saved values sets.
CrystVector_bool	mSavedValuesSetIsUsed
	Is the set associated with (id) currently used ?
long	mNbRefParNotFixed
	Total of not-fixed parameters.
CrystVector_long	mRefparNotFixedIndex
	Index of not-fixed parameters.
bool	mIsbeingRefined
	Is the object being refined ?
ObjRegistry< RefinableObj >	mSubObjRegistry
	Registry of RefinableObject needed for this object (owned by this object or not).
ObjRegistry< RefinableObj >	mClientObjRegistry
	Registry of RefinableObject using this object. This is mutable so that client can modify it (kludge?).
ObjRegistry< RefObjOpt >	mOptionRegistry
	List of options for this object. Note that these are just references, to options allocated by the object, to have a simple global access to all options.
bool	mDeleteRefParInDestructor
	If true (the default), then all RefinablePar will be deleted when the the object is deleted. The opposite option (false) should only be used in RefinableObj holding 'copies' of other objects, such as in algorithms.
RefinableObjClock	mRefParListClock
	Last time the RefinableParList was modified (a parameter added or removed).
bool	mRandomMoveIsDone
	This true is false if RefinableObj::GlobalOptRandomMove() has been called since RefinableObj::BeginGlobalOptRandomMove() was called. More...
Static Protected Attributes
const int	mMaxNbSavedSets = 1000
	Max number of saved sets (memory is dynamically allocated...).

---

Detailed Description

Generic Refinable Object.

This is basically a list of refinable parameters, with other basic common properties such as a name,. etc... This allows optimization/refinement algorithms to access the parameters without knowing what the object really is.

Todo:

Define more clearly which operations are recursive (ie also modify sub-objects).

---

Member Function Documentation

void ObjCryst::RefinableObj::AddOption (  RefObjOpt *    opt )  [protected]

Add an option for this parameter. For internal use only.

void ObjCryst::RefinableObj::AddPar (  RefinableObj &    newRefParList )

Add all the parameters in another RefinableObj. Parameters are \not copied, so they should be allocated in the heap. Warning: If a copy of another RefinableObj parameter list is made, such as in the OptimizationObj class, make sure that upon deletion of this object the parameters will not be destroyed. To do this use RefinableObj::SetDeleteRefParInDestructor(false).

void ObjCryst::RefinableObj::AddPar (  RefinablePar *    newRefPar )

Add a refinable parameter. The parameter is not copied, so it should be allocated in the heap.

void ObjCryst::RefinableObj::AddPar (  const RefinablePar &    newRefPar )

Add a refinable parameter. The parameter is copied, so it need only be allocated temporarily. Deprecated: Use the next function, which supplies the parameter as a pointer, and avoids a useless copy.

void ObjCryst::RefinableObj::AddSubRefObj (  RefinableObj &    )  [protected]

Add an object in the registry of used objects. For internal use only.

void ObjCryst::RefinableObj::BeginGlobalOptRandomMove (    )

Raise a flag, to be sure not to make a random change more than once in each RefinableObj. This calls recursively all sub-objects. This is necessary since one object may be included in several others. This must be called before making a random configuration change on a list of objects.

virtual void ObjCryst::RefinableObj::BeginOptimization (  const bool    allowApproximations = false, const bool    enableRestraints = false )  [virtual]

This should be called by any optimization class at the begining of an optimization. This will also check that everything is ready, eg call the RefinableObj::Prepare() function. This also affects all sub-objects. Note: this may be called several time for some objects which are used by several other objects. Parameters: allowApproximations:  if true, then the object can use faster but less precise functions during the optimization. This is useful for global optimization not using derivatives. enableRestraints:  if true, then restrained parameters will be allowed to go beyond theur hard limits. This implies that the algorithm will take into account the cost (penalty) related to the restraints. Objects which do not use restraints will simply ignore this. Reimplemented in ObjCryst::Crystal, ObjCryst::PowderPatternDiffraction, and ObjCryst::ScatteringData.

long ObjCryst::RefinableObj::CreateParamSet (  const string    name = "" )  const

Save the current set of refined values in a new set. Parameters: name  : the name associated to this set of values. Names should be unique. Returns: an number identifying the set of saved values.

virtual void ObjCryst::RefinableObj::EndOptimization (    )  [virtual]

This should be called by any optimization class at the end of an optimization. This also affects all sub-objects. Note: this may be called several time for some objects which are used by several other objects. Reimplemented in ObjCryst::PowderPatternDiffraction, ObjCryst::ScatteringData, and ObjCryst::ZScatterer.

virtual void ObjCryst::RefinableObj::GetGeneGroup (  const RefinableObj &    obj, CrystVector_uint &    groupIndex, unsigned int &    firstGroup )  const [virtual]

Get the gene group assigned to each parameter. Each parameter (a gene in terms of genetic algorithms) can be assigned to a gene group. Thus when mating two configurations, genes will be exchanged by groups. By default (in the base RefinabeObj class), each parameter is alone in its group. Derived classes can group genes for a better s** life. The number identifying a gene group only has a meaning in a given object. It can also change on subsequent calls, and thus is not unique. Parameters: obj  the \RefinableObj, supplied by an algorithm class (OptimizationObj,..), which contains a list of parameters, some of which (but possibly all or none) are parameters belonging to this object. groupIndex  a vector of unsigned integers, one for each parameter in the input object, giving an unsigned integer value as gene group index. At the beginning this vector should contain only zeros (no group assigned). firstGroup  this is the number of groups which have already been assigned, plus one. The gene groups returned by this object will start from this value, and increment firstGroup for each gene group used, so that different RefinableObj cannot share a gene group. Note: this function is not optimized, and should only be called at the beginning of a refinement. Reimplemented in ObjCryst::Atom, ObjCryst::Crystal, ObjCryst::PowderPatternBackground, ObjCryst::PowderPatternDiffraction, ObjCryst::PowderPattern, ObjCryst::ScatteringPower, and ObjCryst::ZScatterer.

CrystVector_REAL& ObjCryst::RefinableObj::GetParamSet (  const long    setId )

Access one save refpar set. Parameters: setId  : the number identifying the set.

const CrystVector_REAL& ObjCryst::RefinableObj::GetParamSet (  const long    setId )  const

Access one save refpar set. Parameters: setId  : the number identifying the set.

REAL ObjCryst::RefinableObj::GetParamSet_ParNotFixedHumanValue (  const long    setId, const long    parNumber )  const

Access the (human) value of one refined parameter in a saved set of parameters. For internal use only. Parameters: setId  : the number identifying the set. parNumber  : the number identifying the parameter in the list of refined parameters Returns: if parNumber=5 and setId=37, then the returned value will be the value (scaled if it is an angle) value of the 5th not-fixed parameter in the saved set #37.

virtual REAL ObjCryst::RefinableObj::GetRestraintCost (    )  const [virtual]

Get the restraint cost (penalty). Note: by default this returns 0, so this must be overloaded by any object which actually uses retsraint. Todo: Instead, we could return by default the sum of the restraints, but this is dangerous since we need to have objects using restraints fully responsible for them.

virtual void ObjCryst::RefinableObj::GlobalOptRandomMove (  const REAL    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 in ObjCryst::Crystal, and ObjCryst::ZScatterer.

void ObjCryst::RefinableObj::InitRandomSeedFromTime (    )  const [protected]

Init the seed for random number generation from current time. For internal use only.

void ObjCryst::RefinableObj::operator= (  const RefinableObj &    old )

Defined not implemented... Should never be called

virtual void ObjCryst::RefinableObj::Prepare (    )  [protected, virtual]

Prepare everything (if necessary) for an optimization/calculation. For internal use only. Reimplemented in ObjCryst::PowderPatternComponent, ObjCryst::PowderPatternBackground, ObjCryst::PowderPatternDiffraction, and ObjCryst::PowderPattern.

virtual void ObjCryst::RefinableObj::RegisterClient (  RefinableObj &    )  const [virtual]

Register a new object using this object. Todo: : the clients should be const, but are not... This need to be fixed...

void ObjCryst::RefinableObj::RemoveSubRefObj (  RefinableObj &    )  [protected]

Remove an object in the registry of used objects. For internal use only.

void ObjCryst::RefinableObj::RestoreParamSet (  const long    id )

Restore a saved set of values. Parameters: id  : the number identifying the set. Warning: this only affects parameters which are used and not fixed. Others remain unchanged.

void ObjCryst::RefinableObj::SaveParamSet (  const long    id )  const

Save the current set of refined values over a previously-created set of saved values. Parameters: id  the number identifying the set of saved values.

void ObjCryst::RefinableObj::SetDeleteRefParInDestructor (  const bool    b )

Set this object not to delete its list of parameters when destroyed. This is used for the RefinableObj in algorithms objects (OptimizationObj), which only hold copies of parameters from the refined objects.

virtual void ObjCryst::RefinableObj::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 in ObjCryst::Atom, ObjCryst::Crystal, ObjCryst::DiffractionDataSingleCrystal, ObjCryst::PowderPatternBackground, ObjCryst::PowderPatternDiffraction, ObjCryst::PowderPattern, ObjCryst::Radiation, ObjCryst::ScatteringPowerAtom, and ObjCryst::ZScatterer.

virtual void ObjCryst::RefinableObj::XMLOutput (  ostream &    os, int    indent = 0 )  const [virtual]

Output to stream in well-formed XML. Todo: Use inheritance.. as for XMLInputTag()... Reimplemented in ObjCryst::Atom, ObjCryst::Crystal, ObjCryst::DiffractionDataSingleCrystal, ObjCryst::PowderPatternBackground, ObjCryst::PowderPatternDiffraction, ObjCryst::PowderPattern, ObjCryst::Radiation, ObjCryst::ScatteringPowerAtom, and ObjCryst::ZScatterer.

---

Member Data Documentation

bool ObjCryst::RefinableObj::mRandomMoveIsDone [protected]

This true is false if RefinableObj::GlobalOptRandomMove() has been called since RefinableObj::BeginGlobalOptRandomMove() was called. For internal use only.

---

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

• RefinableObj.h

---