\(\renewcommand\AA{\text{Å}}\)

9. GSASIImapvars: Param Constraints

9.1. Summary/Contents

Module to implements algebraic contraints, parameter redefinition and parameter simplification contraints.

9.2. Externally-Accessible 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 string-specified (formula-based) 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 internally-used 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().

9.3. 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 GSAS-II 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 GSAS-II 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.

9.3.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 GSAS-II 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, GSAS-II 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).

9.3.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 GSAS-II 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, GSAS-II 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).

9.3.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 GSAS-II 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, GSAS-II 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 N-1 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 N-1 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). Symmetry-generated equivalences are generated prior to display or refinement in GSASIIstrIO.GetPhaseData(). These are not stored in the data tree.

9.3.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).

9.4. Constraint Processing

When constraints will be used or edited, they are processed using a series of calls. This is done in GSAS-II 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() using GSASIIconstrGUI.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 in GSASIIdataGUI and GSASIIscriptable), which is similar to GSASIIconstrGUI.CheckConstraints(). ReadCheckConstraints() is called by GSASIIdataGUI.GSASII.OnRefine() and GSASIIdataGUI.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 in GSASIIscriptable.G2Project.

• To create the constraints for use in a refinement, in GSASIIstrMain, functions GSASIIstrMain.Refine() and GSASIIstrMain.SeqRefine() load and process the constraints again. This is repeated here because Refine() and SeqRefine() are intended to operate as stand-alone 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:

1. 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.

2. Then InitVars() is used to initialize the global variables in this module (GSASIImapvars). This may be done before the previous step.

3. Then ProcessConstraints() is used to initially process the constraints user-supplied constraints (from the data tree), as described in Constraint Reorganization. When constraints are read from a GPX file, rather than the data tree, use GSASIIstrIO.ReadConstraints() (which calls ProcessConstraints()).

4. Symmetry-generated equivalences are then created in GSASIIstrIO.GetPhaseData(), which also calls GSASIIstrIO.cellVary() and for Pawley refinements GSASIIstrIO.GetPawleyConstr(). These are entered directly into this module’s globals using StoreEquivalence().

5. Constraints/equivalences are then checked for possible conflicts with GenerateConstraints() which in turn calls CheckEquivalences(). These routines group the constraints and possibly reorganize them, as discussed below for GenerateConstraints() (discussed here) and for CheckEquivalences() (discussed here).

6. Note that for debugging, VarRemapShow() can be called at any point after GenerateConstraints() has been called. This will display the generated constraints.

9.4.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, while fixedList 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 in fixedList 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,

User-supplied “Hold” constraints are stored in global variable holdParmList. Initialized in InitVars(); set in StoreHold(). Type of hold is stored in holdParmType.

Equivalences are stored using StoreEquivalence() into this module’s globals

(dependentParmList, arrayList, invarrayList, indParmList, and symGenList). 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]

9.4.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 row-echelon 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 non-singular, 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 Gram-Schmidt process, implemented in GramSchmidtOrtho(), is used to find orthonormal unit vectors which are used to replace the remaining Np-Nc 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 row-echelon form. The Gram-Schmidt 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 Gram-Schmidt 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.

9.4.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. Function CheckEquivalences() is called within GenerateConstraints() to diagnose and where possible resolve such uses, as discussed below.

Mixed parameter use:

Note that multiple passes, cycling through the equivalences may be needed to find all mixed-use parameters, as will be discussed further, 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).

9.5. 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 GSAS-II 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 GetIndependentVars(), and GetDependentVars(). Best if not referenced outside this module. Contains elements: ‘dep-equiv’: dependent parameters set by equivalences ‘dep-constr’: dependent parameters set by constraint equations or new var expressions ‘indep-equiv’: dependent parameters used in equivalences ‘indep-constr’: dependent parameters created from constraint equations or new var expressions
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

9.6. GSASIImapvars Routines/variables

Classes and routines defined in GSASIImapvars follow.

Note that parameter names in GSAS-II 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)

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)

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

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 in CheckEquivalences() (called by GenerateConstraints()) if an infinite loop is detected. Also raised in GramSchmidtOrtho() and _SwapColumns() but caught within GenerateConstraints().

__weakref__

list of weak references to the object

GSASIImapvars.Dict2Deriv(varyList, derivDict, dMdv)

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)

Applies the constraints defined using StoreEquivalence(), GroupConstraints() and GenerateConstraints() by changing values in a dict containing the parameters. This should be done after refinement and before the parameters are used for any computations

Parameters:

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)

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 GSAS-II 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)

Takes a list of relationship entries that have been stored by ProcessConstraints() into lists constrDict and fixedList

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 unless set to None. None is used to indicate that all constraints should be generated.

• 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

GSASIImapvars.GetDependentVars(opt=None)

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.GetDroppedSym(seqmode, seqhistnum)

Return automatically generated (equivalence) relationships that were converted to constraint equations

Returns:

a list of strings containing the details of the equivalences

GSASIImapvars.GetIndependentVars()

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)

Return the automatically generated (equivalence) relationships.

Returns:

a list of strings containing the details of the contraint relationships

GSASIImapvars.GramSchmidtOrtho(a, nkeep=0)

Use the Gram-Schmidt process (http://en.wikipedia.org/wiki/Gram-Schmidt) to find orthonormal unit vectors relative to first row.

If nkeep is non-zero, the first nkeep rows in the array are not changed

input:

arrayin: a 2-D non-singular square array

returns:

a orthonormal set of unit vectors as a square array

GSASIImapvars.GroupConstraints(constrDict)

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.InitVars()

Initializes all constraint information

GSASIImapvars.Map2Dict(parmDict, varyList)

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() and GenerateConstraints() 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='use-all', seqhst=None)

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 ‘use-all’, ‘wildcards-only’ or ‘auto-wildcard’. When seqmode==’wildcards-only’ then any constraint with a numerical histogram number is skipped. With seqmode==’auto-wildcard’, any non-null constraint number is set to the selected histogram.

• seqhst (int) – number for current histogram (used for ‘wildcards-only’ or ‘auto-wildcard’ only). Should be None for non-sequential 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!)

GSASIImapvars.StoreEquivalence(independentVar, dependentList, symGen=True)

Takes a list of dependent parameter(s) and stores their relationship to a single independent parameter (independentVar).

Called with user-supplied constraints by ProcessConstraints(), with Pawley constraints from GSASIIstrIO.GetPawleyConstr(), with Unit Cell constraints from GSASIIstrIO.cellVary() with symmetry-generated atom constraints from GSASIIstrIO.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)

Takes a variable name and prepares it to be removed from the refined variables.

Called with user-supplied constraints by ProcessConstraints(). At present symGen is not used, but could be set up to track Holds generated by symmetry.

GSASIImapvars.SubfromParmDict(s, prmDict)

Process a string as a multiplier and convert it to a float value. This is done by subsituting any GSAS-II 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 GSAS-II parameter names and values the corresponding parameter value.

Returns:

the evaluated expression as a float.

GSASIImapvars.VarKeys(constr)

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)

List out the saved relationships. This should be done after the constraints have been defined using StoreEquivalence(), GroupConstraints() and GenerateConstraints().

Returns:

a string containing the details of the contraint relationships

GSASIImapvars._FillArray(sel, d, collist)

Construct a n by n matrix [n = len(collist)] with the initial m rows [m = len(sel)] using the relationships defined in the expressions dict, d. Since m may be smaller than n, the remaining rows are filled with rows that are tested to not create a singular matrix.

Parameters:

• sel (list) – a list of indices in dict d

• d (list) – a list of dict’s where each dict describes an expression from a constraint equation or a new var

• collist (list) – a list parameter names.

Returns:

an n by n numpy.array matrix

GSASIImapvars._FormatConstraint(RelDict, RelVal)

Formats a Constraint or Function for use in a convenient way

GSASIImapvars._RowEchelon(m, arr, collist)

Convert the first m rows in Matrix arr to row-echelon form exchanging columns in the matrix and collist as needed.

throws an exception if the matrix is singular because the first m rows are not linearly independent

GSASIImapvars._SwapColumns(i, m, v)

Swap columns in matrix m as well as the labels in v so that element (i,i) is replaced by the first non-zero element in row i after that element

Throws an exception if there are no non-zero elements in that row

GSASIImapvars._showEquiv(varlist, mapvars, invmultarr, longmsg=False)

Format an equivalence relationship, note that varlist, mapvars, invmultarr are elements of dependentParmList, indParmList, invarrayList

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 = {'dep-constr': [], 'dep-equiv': [], 'indep-constr': [], 'indep-equiv': []}

A dict with parameters in equivalences, compiled from (dependentParmList) and (indParmList). Used within GetIndependentVars() and GetDependentVars().

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.droppedSym = []

A list of symmetry generated equivalences that have been converted to constraint equations in CheckEquivalences()

GSASIImapvars.getConstrError(constrLst, seqmode, seqhst)

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 ‘use-all’, ‘wildcards-only’ or ‘auto-wildcard’

• seqhst (int) – number for current histogram (used for ‘wildcards-only’ or ‘auto-wildcard’ only). Should be None for non-sequential 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)

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 in InitVars().

GSASIImapvars.holdParmType = {}

The reason why a parameter has been marked as “Hold”. Initialized in InitVars(); set in StoreHold().

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 inverse-relationship matrices that map constrained values and generated (New Var) parameters (in indParmList) to model parameters (in dependentParmList).

GSASIImapvars.multdepVarList = []

parameters used as dependents multiple times in equivalences

GSASIImapvars.normParms(parmDict)

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 in Map2Dict(). Used in VarRemapShow()

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