fix parameter limits and improve their scripting docs, as per #254

Author: briantoby

GSASII/GSASIIctrlGUI.py

@@ -44,9 +44,6 @@
 #from . import GSASIIstrMain as G2stMn
 from . import GSASIImiscGUI as G2IO
 from .tutorialIndex import tutorialIndex
-if sys.version_info[0] >= 3:
-    unicode = str
-    basestring = str
 
 # Define a short names for convenience
 DULL_YELLOW = (230,230,190)
@@ -406,7 +403,7 @@ def __init__(self,parent,loc,key,nDig=None,notBlank=True,xmin=None,xmax=None,
             self.type = int
         elif 'float' in str(type(val)):
             self.type = float
-        elif isinstance(val,str) or isinstance(val,unicode):
+        elif isinstance(val,str):
             self.type = str
         elif val is None:
             raise Exception("ValidatedTxtCtrl error: value of "+str(key)+
@@ -4762,11 +4759,7 @@ def __init__(self,G2frame,title,parmDict,varyList,fullVaryList,
             self.frozenList = []
         # make lists of variables of different types along with lists of parameter names, histogram #s, phase #s,...
         self.parmNames = sorted(list(parmDict.keys()))
-        if '2' in platform.python_version_tuple()[0]:
-            basestr = basestring
-        else:
-            basestr = str
-        splitNames = [item.split(':') for item in self.parmNames if len(item) > 3 and not isinstance(self.parmDict[item],basestr)]
+        splitNames = [item.split(':') for item in self.parmNames if len(item) > 3 and not isinstance(self.parmDict[item],str)]
         globNames = [':'.join(item) for item in splitNames if not item[0] and not item[1]]
         if len(globNames):
             self.choiceDict['Global'] = G2obj.SortVariables(globNames)
@@ -5022,11 +5015,7 @@ def __init__(self, parent):
     def SetContents(self,parent):
         self.varList = []
         for name in parent.choiceDict[parent.parmChoice]:
-            if '2' in platform.python_version_tuple()[0]:
-                basestr = basestring
-            else:
-                basestr = str
-            if isinstance(parent.parmDict[name],basestr): continue
+            if isinstance(parent.parmDict[name],str): continue
             if 'Refined' in parent.listSel and (name not in parent.fullVaryList
                                               ) and (name not in parent.varyList):
                 continue
@@ -5281,19 +5270,24 @@ def SetWildAfter(d,name,wname,mode):
     # Callbacks to display info in table
     def OnGetItemText(self, item, col):
         name = self.varList[item]
+        atmParNam  = None
+        if name.split(':')[2].startswith('dA'):
+            atmParNam = name.replace(':dA',':A')
         if col == 0:
             return str(item)
         elif col == 1:
+            if atmParNam: return atmParNam
             return name
         elif col == 2:
             if name in self.parmWin.fullVaryList and name in self.parmWin.frozenList:
-                    return "F"
+                return "F"
             elif name in self.parmWin.varyList:
                 return "R"
             elif name in self.parmWin.fullVaryList:
                 return "C"
             return ""
         elif col == 3:
+            if atmParNam: name = atmParNam
             try:
                 value = G2fil.FormatSigFigs(self.parmWin.parmDict[name])
             except ValueError:

GSASII/GSASIIscriptable.py

@@ -2843,8 +2843,12 @@ def imageMultiDistCalib(self,imageList=None,verbose=False):
         return parmDict,covData
 
     def set_Frozen(self, variable=None, histogram=None, mode='remove'):
-        '''Removes one or more Frozen variables (or adds one)
-        (See :ref:`Parameter Limits<ParameterLimits>` description.)
+        '''Removes one or more Frozen variables (or adds one),
+        where parameters are frozen after refining outside the 
+        range where their values are allowed due to parameter 
+        limits, when these limits are set.
+        (See :ref:`Parameter Limits<ParameterLimits>` description
+        and :meth:`G2Project.set_Controls` for setting limits.)
         Note that use of this
         will cause the project to be saved if not already done so.
 
@@ -2916,7 +2920,10 @@ def set_Frozen(self, variable=None, histogram=None, mode='remove'):
             return True
 
     def get_Frozen(self, histogram=None):
-        '''Gets a list of Frozen variables.
+        '''Gets a list of Frozen variables, where parameters are
+        frozen after refining outside the range where their values
+        are allowed due to parameter limits, when these limits are 
+        set. 
         (See :ref:`Parameter Limits<ParameterLimits>` description.)
         Note that use of this
         will cause the project to be saved if not already done so.
@@ -3010,8 +3017,11 @@ def get_Controls(self, control, variable=None):
     def set_Controls(self, control, value, variable=None):
         '''Set project controls.
 
-        Note that use of this with control set to parmMin or parmMax
-        will cause the project to be saved if not already done so.
+        Controls determine how refinements are performed, including 
+        setting lower (parmMin) or upper limits (parmMax) values
+        for parameters where you choose to set refinement limits.
+        Note that use of this with to set to parmMin or parmMax
+        will cause the project to be saved, if not already done so.
 
         :param str control: the item to be set. See below for allowed values.
         :param value: the value to be set.
@@ -3029,8 +3039,9 @@ def set_Controls(self, control, value, variable=None):
           Ignored for non-sequential fits.
         * ``'Reverse Seq'``: when True, sequential refinement is performed on the
           reversed list of histograms.
-        * ``'parmMin'`` & ``'parmMax'``: set a maximum or minimum value for a refined
-          parameter. Note that variable will be a GSAS-II variable name,
+        * ``'parmMin'`` & ``'parmMax'``: set a minimum or maximum value
+          for a refined
+          parameter. Note that *variable* will be a GSAS-II variable name,
           optionally with * specified for a histogram or atom number and
           value must be a float.
           (See :ref:`Parameter Limits<ParameterLimits>` description.)

GSASII/GSASIIstrMain.py

@@ -566,15 +566,15 @@ def Refine(GPXfile,dlg=None,makeBack=True,refPlotUpdate=None,newLeBail=False,all
                 # add indirectly computed uncertainties into the esd dict
                 sigDict.update(G2mv.ComputeDepESD(covMatrix,varyList))
                 G2stIO.PrintIndependentVars(parmDict,varyList,sigDict,pFile=printFile)
+                # check for variables outside their allowed range, reset and freeze them
+                frozen = dropOOBvars(varyList,parmDict,sigDict,Controls,parmFrozenList)
                 G2stMth.ApplyRBModels(parmDict,Phases,rigidbodyDict,True)
                 G2stIO.SetRigidBodyModels(parmDict,sigDict,rigidbodyDict,printFile)
                 G2stIO.SetPhaseData(parmDict,sigDict,Phases,rbIds,covData,restraintDict,printFile)
                 G2stIO.SetISOmodes(parmDict,sigDict,Phases,printFile)
                 G2stIO.SetHistogramPhaseData(parmDict,sigDict,Phases,Histograms,calcControls,
                     pFile=printFile,covMatrix=covMatrix,varyList=varyList)
                 G2stIO.SetHistogramData(parmDict,sigDict,Histograms,calcControls,pFile=printFile)
-                # check for variables outside their allowed range, reset and freeze them
-                frozen = dropOOBvars(varyList,parmDict,sigDict,Controls,parmFrozenList)
                 # covData['depSig'] = G2stIO.PhFrExtPOSig  # created in G2stIO.SetHistogramData, no longer used?
                 covData['depSigDict'] = {i:(parmDict[i],sigDict[i]) for i in parmDict if i in sigDict}
                 if len(frozen):
@@ -1201,17 +1201,20 @@ def dropOOBvars(varyList,parmDict,sigDict,Controls,parmFrozenList):
     if parmMinDict or parmMaxDict:
         for name in varyList:
             if name not in parmDict: continue
+            atmParNam  = name
+            if name.split(':')[2].startswith('dA'):
+                atmParNam = name.replace(':dA',':A')
             n,val = G2obj.prmLookup(name,parmMinDict)
             if n is not None:
-                if parmDict[name] < parmMinDict[n]:
-                    parmDict[name] = parmMinDict[n]
+                if parmDict[atmParNam] < parmMinDict[n]:
+                    parmDict[atmParNam] = parmMinDict[n]
                     sigDict[name] = 0.0
                     freeze.append(name)
                     continue
             n,val = G2obj.prmLookup(name,parmMaxDict)
             if n is not None:
-                if parmDict[name] > parmMaxDict[n]:
-                    parmDict[name] = parmMaxDict[n]
+                if parmDict[atmParNam] > parmMaxDict[n]:
+                    parmDict[atmParNam] = parmMaxDict[n]
                     sigDict[name] = 0.0
                     freeze.append(name)
                     continue

docs/source/GSASIIscriptable.rst

@@ -234,8 +234,8 @@ Class :class:`~GSASIIscriptable.G2Project`
 ---------------------------------------------
 
   All GSASIIscriptable scripts will need to create a :class:`~GSASIIscriptable.G2Project` object 
-  either for a new GSAS-II project or to read in an existing project (.gpx) file. 
-  The most commonly used routines in this object are:
+  either for a new GSAS-II project or to read in an existing project (.gpx) file.
+  The table below is not complete but does contain the most commonly used methods in this object:
 
 .. tabularcolumns:: |l|p{3.in}|
 
@@ -256,18 +256,26 @@ method                                                                  Use
 
 :meth:`~GSASIIscriptable.G2Project.add_single_histogram`                Used to read in a single crystal diffraction dataset into a project file.
 
-:meth:`~GSASIIscriptable.G2Project.histogram`                           Finds a histogram from an object, name or random id reference, returning a
-                                                                        a :class:`~GSASIIscriptable.G2PwdrData` or :class:`~GSASIIscriptable.G2Single` object.
+:meth:`~GSASIIscriptable.G2Project.add_SmallAngle`                      Adds a small-angle scattering histogram to a project
 
 :meth:`~GSASIIscriptable.G2Project.histograms`                          Provides a list of histograms in the current project, as :class:`~GSASIIscriptable.G2PwdrData` or
                                                                         as :class:`~GSASIIscriptable.G2Single` objects.
 
+:meth:`~GSASIIscriptable.G2Project.histogram`                           Finds a histogram from an object, name or random id reference, returning a
+                                                                        a :class:`~GSASIIscriptable.G2PwdrData` or :class:`~GSASIIscriptable.G2Single` object.
+
 :meth:`~GSASIIscriptable.G2Project.histType`                            Determines the histogram type from an object, name or random id reference.
 
 :meth:`~GSASIIscriptable.G2Project.phases`                              Provides a list of phases defined in the current project, as :class:`~GSASIIscriptable.G2Phase` objects
 
+:meth:`~GSASIIscriptable.G2Project.phase`                               Finds a phase from an object, name or random id reference, returning a
+                                                                        a :class:`~GSASIIscriptable.G2Phase` object.
+
 :meth:`~GSASIIscriptable.G2Project.images`                              Provides a list of images in the current project, as :class:`~GSASIIscriptable.G2Image` objects
 
+:meth:`~GSASIIscriptable.G2Project.image`                               Finds an image from an object, name or random id reference, returning a
+                                                                        a :class:`~GSASIIscriptable.G2Image` object.
+
 :meth:`~GSASIIscriptable.G2Project.pdfs`                                Provides a list of PDFs in the current project, as :class:`~GSASIIscriptable.G2PDF` objects
 
 :meth:`~GSASIIscriptable.G2Project.seqref`                              Returns a :class:`~GSASIIscriptable.G2SeqRefRes` object if there are Sequential Refinement results
@@ -281,7 +289,8 @@ method                                                                  Use
                                                                         These actions can be performed also in :meth:`~GSASIIscriptable.G2Project.do_refinements`. 
 :meth:`~GSASIIscriptable.G2Project.get_Variable`                        Retrieves the value and esd for a parameter
 :meth:`~GSASIIscriptable.G2Project.get_Covariance`                      Retrieves values and covariance for a set of refined parameters
-:meth:`~GSASIIscriptable.G2Project.set_Controls`                        Set overall GSAS-II control settings such as number of cycles and to set up a sequential
+:meth:`~GSASIIscriptable.G2Project.set_Controls`                        Set overall GSAS-II control settings such as number of cycles and to set parameter limits.
+                                                                        This is also used to set up a sequential
                                                                         fit. (Also see :meth:`~GSASIIscriptable.G2Project.get_Controls` to read values.)
 :meth:`~GSASIIscriptable.G2Project.imageMultiDistCalib`                 Performs a global calibration fit with images at multiple distance settings.
 :meth:`~GSASIIscriptable.G2Project.get_Constraints`                     Retrieves :ref:`constraint definition <Constraint_definitions_table>` entries.
@@ -290,6 +299,10 @@ method                                                                  Use
 :meth:`~GSASIIscriptable.G2Project.add_EqnConstr`                       Adds an equation-type constraint on two or more variables
 :meth:`~GSASIIscriptable.G2Project.add_NewVarConstr`                    Adds an new variable as a constraint on two or more variables
 :meth:`~GSASIIscriptable.G2Project.ComputeWorstFit`                     Determines the parameters that will have the greatest impact on the fit if refined
+:meth:`~GSASIIscriptable.G2Project.get_Frozen`                          Find variables where parameters have refined out of the parameter limit ranges.
+                                                                        Note that parameter limits are set using :meth:`~GSASIIscriptable.G2Project.set_Controls`.
+:meth:`~GSASIIscriptable.G2Project.set_Frozen`                          Adds or removes variables from the list where parameters have refined outside of their limits.
+                                                                        Note that parameter limits are set using :meth:`~GSASIIscriptable.G2Project.set_Controls`.
 ====================================================================    ===============================================================================================================
 
 .. _Class_G2Phase: