8. GSASIImapvars: Parameter constraints¶
Module to implements algebraic contraints, parameter redefinition and parameter simplification contraints.
8.1. ExternallyAccessible Routines¶
To define a set of constrained and unconstrained relations, one
defines a list of dictionary defining constraint parameters and their
values, a list of fixed values for each constraint and a list of
parameters to be varied. In addition, one uses
StoreEquivalence()
to define parameters that are equivalent.
See the Constraints Processing section for details on how
processing of constraints is done.
routine  explanation 

InitVars() 
This is used to clear out all defined previously defined constraint information 
StoreEquivalence() 
Implements parameter redefinition.
This should be called for every set of equivalence relationships.
Use StoreEquivalence() before calling
GenerateConstraints() 
ProcessConstraints() 
Initially constraints of all types are maintained in lists of
dict entries that are stored in the data tree,
with parameters are stored as
G2VarObj objects so that they can
be resolved if the phase/histogram order changes.
ProcessConstraints() processes this list of dict entries,
separating the “Equivalence”, “Hold”, “Const” and “New Var”
entries for subsequent use.
See the Constraint Reorganization
section for more details. 
EvaluateMultipliers() 
Convert any stringspecified (formulabased) multipliers to
numbers. Call this before using GenerateConstraints() .
At present only values in dict for phase (atom/cell) parameters
are used to evaluate multipliers containint formulae,
but this could be changed if needed. 
GenerateConstraints() 
Generates the internallyused tables from constraints and equivalences. Checks for internal consistency and repairs problems where possible. See the Constraint Checking and Grouping and Equivalence Checking sections for more details. 
Map2Dict() 
To determine values for any parameters created in this module, call Map2Dict. This will not apply contraints. 
Dict2Map() 
To apply the constraints and equivalences, call this. It takes values from the new independent parameters and constraints, and applies them to the parameter dict. 
Dict2Deriv() 
This determines derivatives on independent parameters from those on dependent ones. 
ComputeDepESD() 
Use ComputeDepESD to compute uncertainties on dependent variables. 
VarRemapShow() 
Use this to show a summary of the parameter remapping.
Call after GenerateConstraints() . 
8.2. Types of constraints¶
There are four ways to specify constraints, as listed below.
Note that constraints are initially stored in the
main section of the GSASII data tree under heading Constraints
.
This dict has four keys, ‘Hist’, ‘HAP’, ‘Global’, and ‘Phase’,
each containing a list of constraints. An additional set of constraints
are generated for each phase based on symmetry considerations by calling
GSASIIstrIO.GetPhaseData()
.
Note that in the constraints, as stored in the GSASII data tree, parameters
are stored as GSASIIobj.G2VarObj
objects, as these objects allow for
changes in numbering of phases, histograms and atoms since GSASIIobj.G2VarObj
objects
use random Id’s for references.
When constraints are interpreted (in ProcessConstraints()
),
these references are resolved to the numbered objects by looking up random Id’s
so that the parameter object is converted to a string of form ph:hst:VARNAM:at
.
Constraints are initially stored as described in the constraint definitions, where the last value in the list determines which type of constraint is defined.
8.2.1. Alternate parameters (New Var)¶
Parameter redefinition (“New Var” constraints) is done by creating an expression that relates several parameters:
Mx1 * Px + My1 * Py +... = ::newvar1
Mx2 * Px + Mz2 * Pz + ... = ::newvar2
where Pj is a GSASII parameter name and Mjk is a constant (float) multiplier.
Alternately, multipliers Mjk can contain a formula (str) that will be evaluated prior
to the start of the refinement. In a formula, GSASII parameters will be replaced by the
value of the parameter before the formula is evaluated, so 'np.cos(0::Ax:2)'
is a valid
multiplier. At present, only phase (atom/cell) parameters are available for use in
a formula, from the GUI but this can be expanded if needed.
This type of constraint describes an alternate degree of freedom where parameter Px and Py, etc. are varied to keep their ratio fixed according the expression. A new variable parameter is assigned to each degree of freedom when refined. An example where this can be valuable is when two parameters, P1 and P2, have similar values and are highly correlated. It is often better to create a new variable, Ps = P1 + P2, and refine Ps. In the later stages of refinement, a second variable, Pd = P1  P2, can be defined and it can be seen if refining Pd is supported by the data. Another use will be to define parameters that express “irrep modes” in terms of the fundamental structural parameters.
The “New Var” constraints are stored as a type “f” constraint (see definitions).
8.2.2. Constrained parameters (Const)¶
A constraint on a set of variables can be supplied in the form of a linear algebraic equation:
Nx1 * Px + Ny1 * Py +... = C1
where Cn is a constant (float), where Pj is a GSASII parameter name,
and where Njk is a constant multiplier (float) or a formula (str) that will be evaluated prior
to the start of the refinement. In a formula, GSASII parameters will be replaced by the
value of the parameter before the formula is evaluated, so 'np.cos(0::Ax:2)'
is a valid
multiplier. At present, only phase (atom/cell) parameters are available for use in
a formula, but this can be expanded if needed.
These equations set an interdependence between parameters. Common uses of parameter constraints are to set rules that decrease the number of parameters, such as restricting the sum of fractional occupancies for atoms that share a site to sum to unity, thus reducing the effective number of variables by one. Likewise, the Uiso value for a H atom “riding” on a C, N or O atom can be related by a fixed offset (the so called B+1 “rule”).
The “Const” constraints are stored as a type “c” constraint (see definitions).
8.2.3. Equivalenced parameters (Equiv)¶
A simplifed way to set up a constraint equation is to define an equivalence, which can be of form:
C1 * P1 = C2 * Py
or:
C1 * P1 = C2 * P2 = C3 * P3 = ...
where Cn is a constant (float), where Pj is a GSASII parameter name. This
means that parameters Py (or P2 and P3) are determined from (or “slaved” to)
parameter P1. Alternately, equivalences can be created with StoreEquivalence()
where the multipliers can be a formula (str) that will be evaluated prior to the start of
the refinement. In a formula, GSASII parameters will be replaced by the value of the
parameter before the formula is evaluated, so a multiplier can be specifed as '2*np.cos(0::Ax:2)'
.
At present, only phase (atom/cell) parameters are available for use in
such a formula, but this can be expanded if needed.
The first parameter (P1 above) is considered the independent variable and the remaining parameters are dependent variables. The dependent variables are then set from the independent variable.
Note that a constraint expression is conceptually identical to defining constraint equations. The previous set of equalities could also be written as a set of constraint equations in this way:
C1 * P1  C2 * P2 = 0
C1 * P1  C3 * P3 = 0
...
In practice, however, equivalenced parameters are processed in a different and more direct manner than constraint equations.
A parameter can be used in multiple equivalences where it is an independent variable, but if a parameter were used both as a dependent and independent variable then the order that shifts are applied becomes potentially significant. As an example, in this case these two equivalences are “chained”:
C1 * P1 = C2 * P2
C2 * P2 = C3 * P3
where P2 is both a dependent and independent variable. Likewise, if a parameter is used both in equivalences
and in “New Var” or “Const” constraints, it also becomes unclear how this should be processed. It is
possible to specify equivalences that conflict with constraints.
Should parameter be used as both a dependent and an independent variable or if a parameter is used both in
an the equivalence and in a “New Var” or “Const” constraints, the equivalence
is converted to a constraint (Const) to
avoid conflicts. The equivalences that require this are addressed in :GenerateConstraints()
where
CheckEquivalences()
is used to locate problematic variables in equivalences
and then change these equivalences to “Const” equations. Also, unneeded equivalences are removed.
For an example of how equivalences may be used, consider
a material that has N O atoms in the asymmetric unit, all in fairly similar bonding environments
and where the diffraction data are sparse. One may wish to reduce the complexity of the model fit to
these data by defining Uiso for all O atoms to be the same. This is done by selecting Uiso for any one O atom
as an independent variable in a equivalence and setting the remaining N1 other O atom Uiso
variables as dependent parameters with multipliers of 1. This will require that all O atom Uiso values
be identical.
The results of this refinement will be simpler to understand than if a set of
constraint equations is used, because the refined parameter (named as ph::Uiso:n
) will be the
independent variable, corresponding to the first O atom and all other variables would be
expressed in terms of that variable with a single Equivalence expression.
The alternate would require N1 constraint equations, leaving one degree of freedom with a
variable would that is likely only indirectly related to the Uiso values.
Equivalenced parameters (“EQUIV” constraints), when defined by users,
or when created to relate phases, are stored as a type “e”
constraint (see definitions).
Symmetrygenerated equivalences are generated prior
to display or refinement in GSASIIstrIO.GetPhaseData()
.
These are not stored in the data tree.
8.2.4. Hold parameters (Fixed)¶
When parameters are refined where a single refinement flag determines that several variables are refined at the same time (examples are: cell parameters, atom positions, anisotropic displacement parameters, magnetic moments,…) it can be useful to specify that a specific parameter should not be varied. These will most commonly be generated due to symmetry, but under specific conditions, there may be other good reasons to constrain a parameter.
The “Hold” constraints are stored as a type “h” constraint (see definitions).
8.3. Constraint Processing¶
When constraints will be used or edited, they are processed using a series of calls. This is done in GSASII from several locations:
 For error checking from the tree in
GSASIIconstrGUI
,GSASIIconstrGUI.CheckConstraints()
loads constraints from the data tree.  When the table of refined parameters is shown, constraints are also
processed in function
GSASIIdataGUI.GSASII.OnShowLSParms()
usingGSASIIconstrGUI.CheckConstraints()
 To write parameters in the Export sections of the program,
GSASIIIO.loadParmDict()
loads results as well as constraints from the tree. This works a bit differently from the above, so it makes direct calls to the constraints routines.  For error checking from a GPX file
GSASIIstrIO.ReadCheckConstraints()
loads constraints (called inGSASIIdataGUI
andGSASIIscriptable
), which is similar toGSASIIconstrGUI.CheckConstraints()
.ReadCheckConstraints()
is called byGSASIIdataGUI.GSASII.OnRefine()
andGSASIIdataGUI.GSASII.OnSeqRefine()
before constraints are generated for use in refinements so they can be shown in the GUI. This is also called to check for errors inGSASIIscriptable.G2Project
.  To create the constraints for use in a refinement, in
GSASIIstrMain
, functionsGSASIIstrMain.Refine()
andGSASIIstrMain.SeqRefine()
load and process the constraints again. This is repeated here becauseRefine()
andSeqRefine()
are intended to operate as standalone routines that may be called directly.  After sequential fits have been completed, the previously processed
constraint info is read from the sequential results section of the
data tree. Function
GSASIIseqGUI.UpdateSeqResults()
displays the sequential results table also processes constraints.
TODO: Note that G2stIO.makeTwinFrConstr is called only in one place. It probably needs to be included in all of the above.
When constraints are processed, the following steps are used:
 Constraints are stored in separate lists in the data tree to simplify their creation and their GUI display. In the initial processing, all of the stored constraints are appended into a single list.
 Then
InitVars()
is used to initialize the global variables in this module (GSASIImapvars
). This may be done before the previous step.  Then
ProcessConstraints()
is used to initially process the constraints usersupplied constraints (from the data tree), as described in Constraint Reorganization. When constraints are read from a GPX file, rather than the data tree, useGSASIIstrIO.ReadConstraints()
(which callsProcessConstraints()
).  Symmetrygenerated equivalences are then created in
GSASIIstrIO.GetPhaseData()
, which also callsGSASIIstrIO.cellVary()
and for Pawley refinementsGSASIIstrIO.GetPawleyConstr()
. These are entered directly into this module’s globals usingStoreEquivalence()
.  Constraints/equivalences are then checked for possible conflicts with
GenerateConstraints()
, this requires grouping the constraints, as described below. GenerateConstraints()
is then called to create the constraints that will be used, see below for more details. For debugging constraints,
VarRemapShow()
can be called afterGenerateConstraints()
to display the generated constraints.
8.3.1. Constraint Reorganization (ProcessConstraints()
)¶
ProcessConstraints()
is used to initially process the
constraints from the list of dict entries. The “Const” and “New Var” are placed into two
lists (constrDict
and fixedList
) that are later used for parameter
grouping (in GenerateConstraints()
). “Hold” and “Equivalence” constraints are
separated into separate storage.
 For “Const” entries,
 a dict with multiple entries is placed in
constrDict
where each dict key is the parameter name and the value is the multiplier for the parameter, whilefixedList
gets a string value corresponding to the constant value for the expression. For “New Var” entries,
 a dict with multiple entries defined identically to to that used in “Const” entries. The differences between “New Var” and “Const” entries is that for “Const” entries, a constant value (as a string) is placed in
fixedList
while for “New Var” entries corresponding entry infixedList
is None. Also, one or two additional entries are created in the dict for “New Var” constraints: an entry with key “_vary” is given the value of True or False depending on the refinement flag setting; an entry with key “_name” will be created if the “New Var” parameter has a supplied name. For “Hold” entries,
 Usersupplied “Hold” constraints are stored in global variable
holdParmList
. Initialized inInitVars()
; set inStoreHold()
. Type of hold is stored inholdParmType
. Equivalences are stored using
StoreEquivalence()
into this module’s globals(
dependentParmList
,arrayList
,invarrayList
,indParmList
, andsymGenList
). For each equivalence:
 a list with one entry, the name of the independent parameter is placed in
indParmList
; a list with one or more parameter name is placed in
dependentParmList
; the value None is added to
arrayList
; a list of multipliers for each dependent variable is placed in
invarrayList
 an entry of either True or False is placed in
symGenList
, where True indicates that the entry has been generated from symmetry.
The output from ProcessConstraints()
will have the form as below,
where the first entry is a “Const” and the second is a “New Var”.
constrDict = [ {'0:12:Scale': 2.0, '0:14:Scale': 4.0, '0:13:Scale': 3.0, '0:0:Scale': 0.5}, {'2::C(10,6,1)': 1.0, '1::C(10,6,1)': 1.0, '_vary':True}] fixedList = ['5.0', None]
8.3.2. Constraint Checking and Grouping (GenerateConstraints()
)¶
Function GenerateConstraints()
is used to
process the parameter equivalences and constraint lists created in
ProcessConstraints()
(constrDict
and fixedList
). GenerateConstraints()
is used to generate error/warning messages, to set up lists that are used to show this
information for the GUI (using getConstrError()
) and to
generate the information stored in global arrays that are used later to
apply the constraints.
When a sequential refinement is in progress, the constraints are scanned for parameters that have a wildcard (*) for the histogram number, such as 1::Scale which would refer to the phase fraction for Phase ` in every histogram. The “” will be replaced with the number of the current histogram.
Equivalences are checked with CheckEquivalences()
(described in detail
below). This may result in the creation of additional “Hold”
and “Constr” constraints being added to the constrDict
and fixedList
lists.
The “Const” and “New Var” constraint expressions are then scanned for problems:
Constraints cannot be processed without changes if any of the terms within have the following:
Undefined parameters or Multiplier of zero
If any parameters in a constraint are undefined or have a parameter multiplier of zero the constraint group is not used.
If some, but not all, parameters in a constraint are undefined or have a parameter multiplier of zero and remaining valid parameters will be set as “Hold”. One exception: atom position constraints (p::dA[xyz]:#) will be assumed as zero.
Hold (Fixed) parameters and Unvaried parameters: New Var constraints
If any parameters in a new var constraint are either not refined, or are marked as “Hold” the constraint can not be varied. Any parameters in that group will be set as “Hold”
Hold (Fixed) parameters and Unvaried parameters: Constraint Equations
If any parameters in a constraint equation are either not refined, or are marked as “Hold” those parameters can be removed from the constraint, with an adjustment of the equation sum.
Constraint expressions (“Const” and “New Var”) are sorted by routine GroupConstraints()
into
groups so that each group contains the minimum number of entries that
ensures each parameter is referenced in only one group.
This is done by scanning the
list of dicts in constrDict
one by one and making a list
of parameters used in that constraint expression. Any expression that contains
a parameter in that list is added to the current group and those
parameters are added to this list of parameters. The list of ungrouped
expressions is then scanned again until no more expressions are added to the
current group. This process is repeated until every expression has been
placed in a group. Function GroupConstraints()
returns two lists of lists.
The first has, for each group, a list of the indices in constrDict
that comprise the group (there can be only one). The second list contains,
for each group, the unique parameter names in that group.
Each constraint group is then processed. First, wildcard parameters are renamed (in a sequential refinement). Any held parameters that are used in constraints are noted as errors. The number of refined parameters and the number of parameters that are not defined in the current refinement are also noted. It is fine if all parameters in a group are not defined or all are not varied, but if some are defined and others not or some are varied and others not, this constitutes an error.
The contents of each group is then examined. Groups with a single parameter (holds) are ignored. Then for each group, the number of parameters in the group (Np) and the number of expressions in the group (Nc) are counted and for each expression. If Nc > Np, then the constraint is overdetermined, which also constitutes an error.
The parameter multipliers for each expression are then assembled:
M1a * P1 + M2a * P2 +... Mka * Pk
M1b * P1 + M2b * P2 +... Mkb * Pk
...
M1j * P1 + M2j * P2 +... Mkj * Pk
From this it becomes possible to create a Nc x Np matrix, which is called the constraint matrix:
\[\begin{split}\left( \begin{matrix} M_{1a} & M_{2a} &... & M_{ka} \\ M_{1b} & M_{2b} &... & M_{kb} \\ ... \\ M_{1j} & M_{2j} &... & M_{kj} \end{matrix}\right)\end{split}\]
When Nc<Np, then additional rows need to be added to the matrix and to
the vector that contains the value for each row (fixedList
) where
values are None
for New Vars and a constant for fixed values.
This then can describe a system of Np simultaneous equations:
\[\begin{split}\left( \begin{matrix} M_{1a} & M_{2a} &... & M_{ka} \\ M_{1b} & M_{2b} &... & M_{kb} \\ ... \\ M_{1j} & M_{2j} &... & M_{kj} \end{matrix}\right) \left( \begin{matrix} P_{1} \\ P_{2} \\ ... \\ P_{k} \end{matrix}\right) = \left( \begin{matrix} C_{1} & C_{2} & ... & C_{k} \end{matrix}\right)\end{split}\]
This is done by creating a square matrix from the group using
_FillArray()
. The top Nc rows in the matrix are filled
as described above. Then _RowEchelon()
is used to see if
those entries in the matrix can be coverted to rowechelon form. This
will raise an Exception there is linear dependence between the initial Nc rows
(which means that no matter what values are used for any remaining rows, that the matrix
will be singular). If that is not the case and Nc<Np then any remaining rows that
were not specified are filled in. For each of these rows, first only the
diagonal element in that row of the matrix is set to 1
and the upper portion of the matrix is again tested with _RowEchelon()
to check for linear independence. This is likely to be nonsingular,
but should _RowEchelon()
fail,
_FillArray()
will then try setting each other element in that row to either
1 or 1. One of those options should be linearly independent from every other
row of the matrix.
The
GramSchmidt process,
implemented in GramSchmidtOrtho()
, is used to find orthonormal unit
vectors which are used to replace the remaining NpNc rows of the matrix. This will fail with
a ConstraintException
if this is not possible (singular matrix), but that would be
unexpected since the matrix could be converted to rowechelon form. The
GramSchmidt result is placed in constrArr
as a numpy array.
Rows in the matrix corresponding to “New Var” constraints and those that
were generated by the GramSchmidt process are provided with parameter names.
These names are generated using paramPrefix
, which is set to "::constr"
,
plus a number to make the new parameter name unique,
unless a name was specified for the
“New Var” entry by using a "_name"
element in the constraint dict.
Finally the parameters used as input to the constraint are placed in
this module’s globals
dependentParmList
and the constraint matrix is
placed in into arrayList
. This can be used to compute
the initial values for “New Var” parameters. The inverse of the
constraint matrix is placed in invarrayList
and a list
of the “New Var” parameters and a list of the fixed values (as str’s)
is placed in indParmList
.
Finally the appropriate entry in symGenList
is set to
False to indicate that this is not a symmetry generated constraint.
8.3.3. Equivalence Checking and Reorganization (CheckEquivalences()
)¶
Equivalences need to be checked for usages that could be internally conflicted or have possible conflicts with other constraints.
Mixed parameter use:
Note that cycling through the equivalences may be needed to find all mixeduse parameters, see below.
A parameter should not show up as a dependent variable in two equivalence expressions, such as:
::x1 > ::x3 ::x2 > ::x3
This will be processed by turning the equivalences into two constraint equations:
::x1  ::x3 = 0 ::x2  ::x3 = 0
which can be satisfied when
::x1 = ::x2 = ::x3
. If::x1
and::x2
had been intended to be independent parameters, then the above equivalences would be conflict and cannot be statisfied.If a parameter is used both as an independent and as a dependent variable (chaining), as is in these two equivalence expressions:
::x1 > ::x2 & ::x4 ::x2 > ::x3
This can also be addressed by turning these equivalences into three constraint equations:
::x1  ::x2 = 0 ::x1  ::x4 = 0 ::x2  ::x3 = 0
which can be satisfied when
::x1 = ::x2 = ::x3 = ::x4
Use of parameters in both equivalences and “Const” or “New Var” constraint expressions makes logical sense:
::x1 > ::x2 & ::x4 ::x2 + ::x3 = 0
This can also be addressed by turning the equivalence into two constraint equations:
::x1  ::x2 = 0 ::x1  ::x4 = 0
With the addition of the “Const” equation (
::x2 + ::x3 = 0
), the solution will require::x1 = ::x2 = 1.0*::x3 = ::x4
Cycling is needed to find all equivalences that must be converted. Consider this set of constraints:
::x2 + ::x3 = 0 ::x1 > ::x2 ::x1 > ::x4
In the first pass the equivalence with::x2
would be converted to a “Const” constraint and in the second pass the other equivalence with::x1
would be converted.
Mixing Hold (Fixed) parameters in equivalences
If one parameter (or more) is designated as a “Hold” in an equivalence, then all parameters in that equivalence cannot be varied. Considering this equivalence:
::x1 > ::x2 & ::x4
If any of the three parameters (
::x1
,::x2
, or ::x4) are marked as Hold, then the other two parameters may not be varied and will also be set with a “Hold”.
Unvaried parameters in equivalences
 If no parameters in an equivalence are varied, then the equivalence is ignored.
 If only some parameters are marked as varied then none of the parameters can be varied; any varied parameters will be set with a “Hold”.
Undefined parameters in equivalences
Parameters may be placed in equivalences that are not actually defined in a project. This can occur in two ways. If an equivalence is created in the GUI for a parameter that is later supplanted with a different model (for example, changing from isotropic size broadening to uniaxial broadening replaces the isotropic broadening term with two different uniaxial terms) or symmetry may require restrictions on anisotropic ADPs that are not in use).
 If the independent parameter is undefined, then any dependent parameters that are defined are set as “Hold” and the equivalence is ignored.
 If all dependent parameters are undefined, then the equivalence is ignored.
 If a dependent parameter is undefined, then that parameter is dropped from the equivalence.
Multiplier of zero in equivalences
Any dependent parameter that has a multiplier of zero will be dropped from the equivalence. If no terms remain, then the equivalence is ignored. (Independent parameters do not have a multiplier).
8.4. Global Variables¶
This module uses a number of global variables. One set is used to store the
constraints and equivalences after processing by StoreEquivalence()
and
GenerateConstraints()
.
These globals are expected to be used only by this module’s (GSASIImapvars
) internal routines.
Lists with information from Constraint Equation and New Var constraints. Each entry in these variables is related to a group of constraints.
variable  explanation 

dependentParmList 
a list containing group of lists of
parameters used in the group.
The columns of the matrices in arrayList match
the order of parameters here.
Note that parameters listed in
dependentParmList will not be included in the Hessian as their
derivatives will not affect the model 
indParmList 
a list containing groups of variables or constants matching
the columns of the matrices in invarrayList . 
arrayList 
a list containing group of relationship matrices to relate parameters in dependentParmList to those in indParmList. 
invarrayList 
a list containing group of relationship matrices to relate parameters in indParmList to those in dependentParmList. Unlikely to be used externally. 
symGenList 
a list of boolean values that will be True to indicate that an equivalence was generated internally GSASII meaning it is generated based on symmetry, twining or Pawley overlap. 
Lists with information from Hold and Equivalence constraints. Each entry in these variables is related to a group of constraints.
variable  explanation 

holdParmList 
a list of parameters that have been marked as “Hold”.
Unlikely to be accessed outside this module.
Initialized in InitVars() ; set in StoreHold() . 
holdParmType 
The reason why a parameter has been marked as “Hold”.
Unlikely to be accessed outside this module.
Initialized in InitVars() ; set in StoreHold() . 
constrParms 
dict with lists of variables in equivalences,
constraint equations and new var expressions.
Used within

saveVaryList 
a list of the varied parameters used when constraints were last processed. 
A second set of global variables are set in GenerateConstraints()
with lists of parameter
names from equivalences and constraints. Used in CheckEquivalences()
and
getConstrError()
.
variable  explanation 

depVarList 
a list of the parameters used in equivalences as dependent parameters for all equivalences initially specified (including those to be reclassified as “Constr” constraints.) 
indepVarList 
a list of the parameters used in equivalences as independent parameters for all equivalences initially specified (including those to be reclassified as “Constr” constraints.) 
constrVarList 
a list of the parameters that are used in “Constr” or “New Var” constraints. Does not include those in equivalences to be reclassified as “Constr” constraints.) 
A third set of global variables to store equivalence warning information.
Set in CheckEquivalences()
and GenerateConstraints()
.
Used in getConstrError()
to display warning messages.
variable  explanation 

convVarList 
parameters in equivalences that were converted to “Const” constraints 
multdepVarList 
parameters used as dependent parameters in equivalences multiple times 
unvariedParmsList 
parameters used in equivalences and constraints that are not varied 
undefinedVars 
parameters used in equivalences that are not defined in the parameter dict (parmDict) 
groupErrors 
parameters in constraints that cause grouping errors 
8.5. GSASIImapvars Routines/variables¶
Note that parameter names in GSASII are strings of form <ph#>:<hst#>:<nam>
or <ph#>::<nam>:<at#>
where <ph#>
is a phase number, <hst#>
is a histogram number and <at#>
is an atom number.
<nam>
is a name that determines the parameter type (see GSASIIobj.CompileVarDesc()
). When
stored in the data tree, parameters are saved as GSASIIobj.G2VarObj
objects
so that they can be resolved if the phase/histogram order changes.

GSASIImapvars.
CheckEquivalences
(constrDict, varyList, fixedList, parmDict=None, seqHistNum=None)[source]¶ Process equivalence constraints, looking for conflicts such as where a parameter is used in both an equivalence and a constraint expression or where chaining is done (A>B and B>C).
Removes equivalences or parameters from equivalences or converts equivalences to constraints as described for Equivalence Checking and Reorganization.
Parameters:  constrDict (dict) – a list of dicts defining relationships/constraints
 varyList (list) – list of varied parameters (defined during refinements only)
 fixedList (list) – a list of values specifying a fixed value for each
dict in constrDict. Values are either strings that can be converted to
floats or
None
if the constraint defines a new parameter rather than a constant.  parmDict (dict) – a dict containing defined parameters and their values. Used to find equivalences where a parameter is has been removed from a refinement.
 seqHistNum (int) – the hId number of the current histogram in a sequential fit. None (default) otherwise.
Returns: warning messages about changes that need to be made to equivalences

GSASIImapvars.
ComputeDepESD
(covMatrix, varyList, noSym=False)[source]¶ Compute uncertainties for dependent parameters from independent ones returns a dictionary containing the esd values for dependent parameters
Parameters:  covMatrix (np.array) – the full covariance matrix
 varyList (list) – the names of the variables matching the columns and rows in covMatrix
 noSym (bool) – When True symmetry generated parameters are not included. Do this so that redundant s.u.’s eare not shown. When False (default) s.u. values for all dependent parameters are placed in the returned dict.

exception
GSASIImapvars.
ConstraintException
[source]¶ Defines an Exception that is used when an exception is raised processing constraints. Raised in
GenerateConstraints()
during sequential fits. Possible (but highly unlikely) to be raised inCheckEquivalences()
(called byGenerateConstraints()
) if an infinite loop is detected. Also raised inGramSchmidtOrtho()
and_SwapColumns()
but caught withinGenerateConstraints()
.

GSASIImapvars.
Dict2Deriv
(varyList, derivDict, dMdv)[source]¶ Compute derivatives for Independent Parameters from the derivatives for the original parameters
Parameters:  varyList (list) – a list of parameters names that will be varied
 derivDict (dict) – a dict containing derivatives for parameter values keyed by the parameter names.
 dMdv (list) – a Jacobian, as a list of np.array containing derivatives for dependent parameter computed from derivDict

GSASIImapvars.
Dict2Map
(parmDict)[source]¶ Applies the constraints defined using
StoreEquivalence()
,GroupConstraints()
andGenerateConstraints()
by changing values in a dict containing the parameters. This should be done after refinement and before the parameters are used for any computationsParameters: parmDict (dict) – a dict containing parameter values keyed by the parameter names. After this is called, all the dependent variables will be updated based on constraints and equivalences.

GSASIImapvars.
EvaluateMultipliers
(constList, *dicts)[source]¶ Convert multipliers for constraints and equivalences that are specified as strings into values. The strings can specify values in the parameter dicts as well as normal Python functions, such as “2*np.cos(0::Ax:2/2.)”
Parameters:  constList (list) – a list of dicts containing constraint expressions
 *dicts – one or more dicts containing GSASII parameters and their values can be specified
Returns: an empty string if there were no errors, or an error message listing the strings that could not be converted.

GSASIImapvars.
GenerateConstraints
(varyList, constrDict, fixedList, parmDict=None, seqHistNum=None, raiseException=False)[source]¶ Takes a list of relationship entries that have been stored by
ProcessConstraints()
into listsconstrDict
andfixedList
This routine then calls
CheckEquivalences()
for internal consistency. This includes converting equivalenced variables into constraints when a variable is used in both.Once checked, parameters are grouped so that any parameters that are used in more than one constraint are grouped together. This allows checking for incompatible logic (for example, when four constraints are specified for three variables).
If parmDict is not None, the parameter groups are checked for constraints where some parameters are varied, but not others. If so, the value for that unvaried parameter is subtracted from the constant in the constraint.
Once all checks are complete, the constraints are then converted to the form used to apply them, saving them as global variables within this module.
Parameters:  varyList (list) – a list of parameters names (strings of form
<ph>:<hst>:<nam>
) that will be varied. Note that this is changed here.  constrDict (dict) – a list of dicts defining relationships/constraints
(as described in
GroupConstraints()
)  fixedList (list) – a list of values specifying a fixed value for each dict in constrDict. Values are either strings that can be converted to floats, float values or None if the constraint defines a new parameter.
 parmDict (dict) – a dict containing all parameters defined in current refinement.
 seqHistNum (int) – the hId number of the current histogram in a sequential fit. None (default) otherwise.
 raiseException (bool) – When True, generation of an error causes an exception to be raised (used in sequential fits)
Returns: errmsg,warning,groups,parmlist
 errmsg
Is an error message or empty if no errors were found
 warning
Is a warning message about constraints that have been ignored or changed
 groups
Lists parameter groups
 parmlist
Lists parameters in each parameter groups
 varyList (list) – a list of parameters names (strings of form

GSASIImapvars.
GetDependentVars
(opt=None)[source]¶ Return a list of dependent variables: e.g. parameters that are constrained in terms of other parameters
Parameters: opt (str) – type of dependent variables. ‘equiv’: from equivalences, ‘constr’: from constraints None (default): all Returns: a list of parameter names

GSASIImapvars.
GetIndependentVars
()[source]¶ Return a list of independent variables: e.g. parameters that are slaved to other parameters by constraints
Returns: a list of parameter names

GSASIImapvars.
GetSymEquiv
(seqmode, seqhistnum)[source]¶ Return the automatically generated (equivalence) relationships.
Returns: a list of strings containing the details of the contraint relationships

GSASIImapvars.
GramSchmidtOrtho
(a, nkeep=0)[source]¶ Use the GramSchmidt process (http://en.wikipedia.org/wiki/GramSchmidt) to find orthonormal unit vectors relative to first row.
If nkeep is nonzero, the first nkeep rows in the array are not changed
 input:
 arrayin: a 2D nonsingular square array
 returns:
 a orthonormal set of unit vectors as a square array

GSASIImapvars.
GroupConstraints
(constrDict)[source]¶ Divide the constraints into groups that share no parameters.
Parameters: constrDict (dict) – a list of dicts defining relationships/constraints constrDict = [{<constr1>}, {<constr2>}, ...]
where {<constr1>} is {‘var1’: mult1, ‘var2’: mult2,… }
Returns: two lists of lists:  a list of grouped contraints where each constraint grouped containts a list of indices for constraint constrDict entries
 a list containing lists of parameter names contained in each group

GSASIImapvars.
Map2Dict
(parmDict, varyList)[source]¶ Updates the parameter dictionary and the varyList using the equivalence and constraint input. This should be called at least once, after the constraints have been defined using
StoreEquivalence()
,GroupConstraints()
andGenerateConstraints()
and before any parameter refinement is done.This completes the parameter dictionary by defining values for parameters created by constraints based on the constraints that define them using the values for the current parameters. It also removes all dependent variables from the varyList
Parameters:  parmDict (dict) – a dict containing parameter values keyed by the parameter names. For new variables created by constraints, entries will be added to the dictionary, if not alreay present, or the values will be recomputed.
 varyList (list) – a list of parameters names. Will be modified.

GSASIImapvars.
ProcessConstraints
(constList, seqmode='useall', seqhst=None)[source]¶ Interpret the constraints in the constList input into a dictionary, etc. All
GSASIIobj.G2VarObj
objects are mapped to the appropriate phase/hist/atoms based on the object internals (random Ids). If this can’t be done (if a phase has been deleted, etc.), the variable is ignored. If the constraint cannot be used due to too many dropped variables, it is counted as ignored. In the case of sequential refinements, the current histogram number is substituted for a histogram number of “*”.NB: this processing does not include symmetry imposed constraints
Parameters:  constList (list) – a list of lists where each item in the outer list
specifies a constraint of some form, as described in the
GSASIIobj
Constraint definitions.  seqmode (str) – one of ‘useall’, ‘wildcardsonly’ or ‘autowildcard’. When seqmode==’wildcardsonly’ then any constraint with a numerical histogram number is skipped. With seqmode==’autowildcard’, any nonnull constraint number is set to the selected histogram.
 seqhst (int) – number for current histogram (used for ‘wildcardsonly’ or ‘autowildcard’ only). Should be None for nonsequential fits.
Returns: a tuple of (constrDict,fixedList,ignored) where:
 constrDict (list of dicts) contains the constraint relationships
 fixedList (list) contains the fixed values for each type of constraint.
 ignored (int) counts the number of invalid constraint items (should always be zero!)
 constList (list) – a list of lists where each item in the outer list
specifies a constraint of some form, as described in the

GSASIImapvars.
StoreEquivalence
(independentVar, dependentList, symGen=True)[source]¶ Takes a list of dependent parameter(s) and stores their relationship to a single independent parameter (independentVar).
Called with usersupplied constraints by
ProcessConstraints()
, with Pawley constraints fromGSASIIstrIO.GetPawleyConstr()
, with Unit Cell constraints fromGSASIIstrIO.cellVary()
with symmetrygenerated atom constraints fromGSASIIstrIO.GetPhaseData()
There is no harm in using StoreEquivalence with the same independent variable:
StoreEquivalence('x',('y',)) StoreEquivalence('x',('z',))
but the same outcome can be obtained with a single call:
StoreEquivalence('x',('y','z'))
The latter will run more efficiently.
Note that mixing independent and dependent variables, such as:
StoreEquivalence('x',('y',)) StoreEquivalence('y',('z',))
is a poor choice. The module will attempt to fix this by transforming the equivalence to a “Const” constraint.
Parameters:  independentVar (str) – name of master parameter that will be used to determine the value to set the dependent variables
 dependentList (list) – a list of parameters that will set from
independentVar. Each item in the list can be a string with the parameter
name or a tuple containing a name and multiplier:
['::parm1',('::parm2',.5),]

GSASIImapvars.
StoreHold
(var, holdType=None)[source]¶ Takes a variable name and prepares it to be removed from the refined variables.
Called with usersupplied constraints by
ProcessConstraints()
. At present symGen is not used, but could be set up to track Holds generated by symmetry.

GSASIImapvars.
SubfromParmDict
(s, prmDict)[source]¶ Process a string as a multiplier and convert it to a float value. This is done by subsituting any GSASII parameter names that appear in the string that have associated values in the parameter dict with the value for that parameter.
Parameters:  s (str) – a string to be converted to a value
 prmDict (dict) – a dictionary with keys as GSASII parameter names and values the corresponding parameter value.
Returns: the evaluated expression as a float.

GSASIImapvars.
VarKeys
(constr)[source]¶ Finds the keys in a constraint that represent parameters e.g. eliminates any that start with ‘_’
Parameters: constr (dict) – a single constraint entry of form:
{'var1': mult1, 'var2': mult2,... '_notVar': val,...}
(see
GroupConstraints()
)Returns: a list of keys where any keys beginning with ‘_’ are removed.

GSASIImapvars.
VarRemapShow
(varyList=None, inputOnly=False, linelen=60)[source]¶ List out the saved relationships. This should be done after the constraints have been defined using
StoreEquivalence()
,GroupConstraints()
andGenerateConstraints()
.Returns: a string containing the details of the contraint relationships

GSASIImapvars.
arrayList
= []¶ a list of of relationship matrices that map model parameters in each constraint group (in
dependentParmList
) to generated (New Var) parameters.

GSASIImapvars.
consNum
= 0¶ The number to be assigned to the next constraint to be created

GSASIImapvars.
constrParms
= {'depconstr': [], 'depequiv': [], 'indepconstr': [], 'indepequiv': []}¶ A dict with parameters in equivalences, compiled from (
dependentParmList
) and (indParmList
). Used withinGetIndependentVars()
andGetDependentVars()
.

GSASIImapvars.
constrVarList
= []¶ List of parameters used in “Constr” and “New Var” constraints

GSASIImapvars.
convVarList
= []¶ parameters in equivalences that were converted to “Const” constraints

GSASIImapvars.
depVarList
= []¶ A list of all dependent parameters in equivalences

GSASIImapvars.
dependentParmList
= []¶ a list of lists where each item contains a list of parameters in each constraint group. note that parameters listed in dependentParmList should not be refined directly.

GSASIImapvars.
getConstrError
(constrLst, seqmode, seqhst)[source]¶ This is used to display error messages for constraints and equivalence relations
Parm list constrLst: a single constraint or equivalence as saved in the data tree (see constraint definitions).
Parameters:  seqmode (str) – one of ‘useall’, ‘wildcardsonly’ or ‘autowildcard’
 seqhst (int) – number for current histogram (used for ‘wildcardsonly’ or ‘autowildcard’ only). Should be None for nonsequential fits.
Returns: error, msg where error (bool) is True if the constraint/equivalence creates an error, msg (str) can be a warning or an error

GSASIImapvars.
getInvConstraintEq
(var, varyList)[source]¶ For a dependent variable, find the constraint that defines the dependent variable in terms of varied independent variables. This works for constraint equations (via new var or generated parameters) or equivalences. For equivalences the result will lists of length 1
Parameters:  var (str) – named of refined variable (e.g. 0:0:Scale)
 varyList (list) – list of refined variables
Returns: vList,mList where vList is a list of variables and mList is a list of multipliers for that variable (floats)

GSASIImapvars.
groupErrors
= []¶ parameters in constraints where parameter grouping and matrix inversion fails

GSASIImapvars.
holdParmList
= []¶ List of parameters that should not be refined (“Hold”s). Set in
StoreHold()
. Initialized inInitVars()
.

GSASIImapvars.
holdParmType
= {}¶ The reason why a parameter has been marked as “Hold”. Initialized in
InitVars()
; set inStoreHold()
.

GSASIImapvars.
indParmList
= []¶ a list of lists where each item contains a list for each constraint group with fixed values for constraint equations and names of generated/New Var parameters. In the case of equivalences, the name of a single independent parameter is stored.

GSASIImapvars.
indepVarList
= []¶ A list of all independent parameters in equivalences

GSASIImapvars.
invarrayList
= []¶ a list of of inverserelationship matrices that map constrained values and generated (New Var) parameters (in
indParmList
) to model parameters (independentParmList
).

GSASIImapvars.
multdepVarList
= []¶ parameters used as dependents multiple times in equivalences

GSASIImapvars.
normParms
(parmDict)[source]¶ Attempt to put parameters into the right ballpark by scaling to enforce constraint equations

GSASIImapvars.
paramPrefix
= '::constr'¶ A prefix for generated parameter names

GSASIImapvars.
saveVaryList
= []¶ A list of the varied parameters that was last supplied when constraints were processed. This is set in
GenerateConstraints()
and updated inMap2Dict()
. Used inVarRemapShow()

GSASIImapvars.
symGenList
= []¶ A list of flags that if True indicates a constraint was generated by symmetry

GSASIImapvars.
undefinedVars
= []¶ parameters used in equivalences that are not defined in the parameter dict

GSASIImapvars.
unvariedParmsList
= []¶ parameters used in equivalences that are not varied