source: sasmodels/sasmodels/modelinfo.py @ 1711569

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 1711569 was 1711569, checked in by Torin Cooper-Bennun <torin.cooper-bennun@…>, 15 months ago

fix 'degress' typo

  • Property mode set to 100644
File size: 45.0 KB
Line 
1"""
2Model Info and Parameter Tables
3===============================
4
5Defines :class:`ModelInfo` and :class:`ParameterTable` and the routines for
6manipulating them.  In particular, :func:`make_model_info` converts a kernel
7module into the model info block as seen by the rest of the sasmodels library.
8"""
9from __future__ import print_function
10
11from copy import copy
12from os.path import abspath, basename, splitext
13import inspect
14
15import numpy as np  # type: ignore
16
17# Optional typing
18# pylint: disable=unused-import
19try:
20    from typing import Tuple, List, Union, Dict, Optional, Any, Callable, Sequence, Set
21    from types import ModuleType
22except ImportError:
23    pass
24else:
25    Limits = Tuple[float, float]
26    #LimitsOrChoice = Union[Limits, Tuple[Sequence[str]]]
27    ParameterDef = Tuple[str, str, float, Limits, str, str]
28    ParameterSetUser = Dict[str, Union[float, List[float]]]
29    ParameterSet = Dict[str, float]
30    TestInput = Union[str, float, List[float], Tuple[float, float], List[Tuple[float, float]]]
31    TestValue = Union[float, List[float]]
32    TestCondition = Tuple[ParameterSetUser, TestInput, TestValue]
33# pylint: enable=unused-import
34
35# If MAX_PD changes, need to change the loop macros in kernel_iq.c
36MAX_PD = 5 #: Maximum number of simultaneously polydisperse parameters
37
38# assumptions about common parameters exist throughout the code, such as:
39# (1) kernel functions Iq, Iqxy, Iqac, Iqabc, form_volume, ... don't see them
40# (2) kernel drivers assume scale is par[0] and background is par[1]
41# (3) mixture models drop the background on components and replace the scale
42#     with a scale that varies from [-inf, inf]
43# (4) product models drop the background and reassign scale
44# and maybe other places.
45# Note that scale and background cannot be coordinated parameters whose value
46# depends on the some polydisperse parameter with the current implementation
47COMMON_PARAMETERS = [
48    ("scale", "", 1, (0.0, np.inf), "", "Source intensity"),
49    ("background", "1/cm", 1e-3, (-np.inf, np.inf), "", "Source background"),
50]
51assert (len(COMMON_PARAMETERS) == 2
52        and COMMON_PARAMETERS[0][0] == "scale"
53        and COMMON_PARAMETERS[1][0] == "background"), "don't change common parameters"
54
55
56def make_parameter_table(pars):
57    # type: (List[ParameterDef]) -> ParameterTable
58    """
59    Construct a parameter table from a list of parameter definitions.
60
61    This is used by the module processor to convert the parameter block into
62    the parameter table seen in the :class:`ModelInfo` for the module.
63    """
64    processed = []
65    for p in pars:
66        if not isinstance(p, (list, tuple)) or len(p) != 6:
67            raise ValueError("Parameter should be [name, units, default, limits, type, desc], but got %r"
68                             %str(p))
69        processed.append(parse_parameter(*p))
70    partable = ParameterTable(processed)
71    partable.check_angles()
72    return partable
73
74def parse_parameter(name, units='', default=np.NaN,
75                    user_limits=None, ptype='', description=''):
76    # type: (str, str, float, Sequence[Any], str, str) -> Parameter
77    """
78    Parse an individual parameter from the parameter definition block.
79
80    This does type and value checking on the definition, leading
81    to early failure in the model loading process and easier debugging.
82    """
83    # Parameter is a user facing class.  Do robust type checking.
84    if not isstr(name):
85        raise ValueError("expected string for parameter name %r"%name)
86    if not isstr(units):
87        raise ValueError("expected units to be a string for %s"%name)
88
89    # Process limits as [float, float] or [[str, str, ...]]
90    choices = []  # type: List[str]
91    if user_limits is None:
92        limits = (-np.inf, np.inf)
93    elif not isinstance(user_limits, (tuple, list)):
94        raise ValueError("invalid limits for %s"%name)
95    else:
96        # if limits is [[str,...]], then this is a choice list field,
97        # and limits are 1 to length of string list
98        if isinstance(user_limits[0], (tuple, list)):
99            choices = user_limits[0]
100            limits = (0., len(choices)-1.)
101            if not all(isstr(k) for k in choices):
102                raise ValueError("choices must be strings for %s"%name)
103        else:
104            try:
105                low, high = user_limits
106                limits = (float(low), float(high))
107            except Exception:
108                raise ValueError("invalid limits for %s: %r"%(name, user_limits))
109            if low >= high:
110                raise ValueError("require lower limit < upper limit")
111
112    # Process default value as float, making sure it is in range
113    if not isinstance(default, (int, float)):
114        raise ValueError("expected default %r to be a number for %s"
115                         % (default, name))
116    if default < limits[0] or default > limits[1]:
117        raise ValueError("default value %r not in range for %s"
118                         % (default, name))
119
120    # Check for valid parameter type
121    if ptype not in ("volume", "orientation", "sld", "magnetic", ""):
122        raise ValueError("unexpected type %r for %s" % (ptype, name))
123
124    # Check for valid parameter description
125    if not isstr(description):
126        raise ValueError("expected description to be a string")
127
128    # Parameter id for name[n] does not include [n]
129    if "[" in name:
130        if not name.endswith(']'):
131            raise ValueError("Expected name[len] for vector parameter %s"%name)
132        pid, ref = name[:-1].split('[', 1)
133        ref = ref.strip()
134    else:
135        pid, ref = name, None
136
137    # automatically identify sld types
138    if ptype == '' and (pid.startswith('sld') or pid.endswith('sld')):
139        ptype = 'sld'
140
141    # Check if using a vector definition, name[k], as the parameter name
142    if ref:
143        if ref == '':
144            raise ValueError("Need to specify vector length for %s"%name)
145        try:
146            length = int(ref)
147            control = None
148        except ValueError:
149            length = None
150            control = ref
151    else:
152        length = 1
153        control = None
154
155    # Build the parameter
156    parameter = Parameter(name=name, units=units, default=default,
157                          limits=limits, ptype=ptype, description=description)
158
159    # TODO: need better control over whether a parameter is polydisperse
160    parameter.polydisperse = ptype in ('orientation', 'volume')
161    parameter.relative_pd = ptype == 'volume'
162    parameter.choices = choices
163    parameter.length = length
164    parameter.length_control = control
165
166    return parameter
167
168
169def expand_pars(partable, pars):
170    # type: (ParameterTable, ParameterSetUser) ->  ParameterSet
171    """
172    Create demo parameter set from key-value pairs.
173
174    *pars* are the key-value pairs to use for the parameters.  Any
175    parameters not specified in *pars* are set from the *partable* defaults.
176
177    If *pars* references vector fields, such as thickness[n], then support
178    different ways of assigning the demo values, including assigning a
179    specific value (e.g., thickness3=50.0), assigning a new value to all
180    (e.g., thickness=50.0) or assigning values using list notation.
181    """
182    if pars is None:
183        result = partable.defaults
184    else:
185        lookup = dict((p.id, p) for p in partable.kernel_parameters)
186        result = partable.defaults.copy()
187        scalars = dict((name, value) for name, value in pars.items()
188                       if name not in lookup or lookup[name].length == 1)
189        vectors = dict((name, value) for name, value in pars.items()
190                       if name in lookup and lookup[name].length > 1)
191        #print("lookup", lookup)
192        #print("scalars", scalars)
193        #print("vectors", vectors)
194        if vectors:
195            for name, value in vectors.items():
196                if np.isscalar(value):
197                    # support for the form
198                    #    dict(thickness=0, thickness2=50)
199                    for k in range(1, lookup[name].length+1):
200                        key = name+str(k)
201                        if key not in scalars:
202                            scalars[key] = value
203                else:
204                    # supoprt for the form
205                    #    dict(thickness=[20,10,3])
206                    for (k, v) in enumerate(value):
207                        scalars[name+str(k+1)] = v
208        result.update(scalars)
209        #print("expanded", result)
210
211    return result
212
213def prefix_parameter(par, prefix):
214    # type: (Parameter, str) -> Parameter
215    """
216    Return a copy of the parameter with its name prefixed.
217    """
218    new_par = copy(par)
219    new_par.name = prefix + par.name
220    new_par.id = prefix + par.id
221
222def suffix_parameter(par, suffix):
223    # type: (Parameter, str) -> Parameter
224    """
225    Return a copy of the parameter with its name prefixed.
226    """
227    new_par = copy(par)
228    # If name has the form x[n], replace with x_suffix[n]
229    new_par.name = par.id + suffix + par.name[len(par.id):]
230    new_par.id = par.id + suffix
231
232class Parameter(object):
233    """
234    The available kernel parameters are defined as a list, with each parameter
235    defined as a sublist with the following elements:
236
237    *name* is the name that will be displayed to the user.  Names
238    should be lower case, with words separated by underscore.  If
239    acronyms are used, the whole acronym should be upper case. For vector
240    parameters, the name will be followed by *[len]* where *len* is an
241    integer length of the vector, or the name of the parameter which
242    controls the length.  The attribute *id* will be created from name
243    without the length.
244
245    *units* should be one of *degrees* for angles, *Ang* for lengths,
246    *1e-6/Ang^2* for SLDs.
247
248    *default value* will be the initial value for  the model when it
249    is selected, or when an initial value is not otherwise specified.
250
251    *limits = [lb, ub]* are the hard limits on the parameter value, used to
252    limit the polydispersity density function.  In the fit, the parameter limits
253    given to the fit are the limits  on the central value of the parameter.
254    If there is polydispersity, it will evaluate parameter values outside
255    the fit limits, but not outside the hard limits specified in the model.
256    If there are no limits, use +/-inf imported from numpy.
257
258    *type* indicates how the parameter will be used.  "volume" parameters
259    will be used in all functions.  "orientation" parameters are not passed,
260    but will be used to convert from *qx*, *qy* to *qa*, *qb*, *qc* in calls to
261    *Iqxy* and *Imagnetic*.  If *type* is the empty string, the parameter will
262    be used in all of *Iq*, *Iqxy* and *Imagnetic*.  "sld" parameters
263    can automatically be promoted to magnetic parameters, each of which
264    will have a magnitude and a direction, which may be different from
265    other sld parameters. The volume parameters are used for calls
266    to form_volume within the kernel (required for volume normalization)
267    and for calls to ER and VR for effective radius and volume ratio
268    respectively.
269
270    *description* is a short description of the parameter.  This will
271    be displayed in the parameter table and used as a tool tip for the
272    parameter value in the user interface.
273
274    Additional values can be set after the parameter is created:
275
276    * *length* is the length of the field if it is a vector field
277
278    * *length_control* is the parameter which sets the vector length
279
280    * *is_control* is True if the parameter is a control parameter for a vector
281
282    * *polydisperse* is true if the parameter accepts a polydispersity
283
284    * *relative_pd* is true if that polydispersity is a portion of the
285      value (so a 10% length dipsersity would use a polydispersity value
286      of 0.1) rather than absolute dispersisity (such as an angle plus or
287      minus 15 degrees).
288
289    *choices* is the option names for a drop down list of options, as for
290    example, might be used to set the value of a shape parameter.
291
292    These values are set by :func:`make_parameter_table` and
293    :func:`parse_parameter` therein.
294    """
295    def __init__(self, name, units='', default=None, limits=(-np.inf, np.inf),
296                 ptype='', description=''):
297        # type: (str, str, float, Limits, str, str) -> None
298        self.id = name.split('[')[0].strip() # type: str
299        self.name = name                     # type: str
300        self.units = units                   # type: str
301        self.default = default               # type: float
302        self.limits = limits                 # type: Limits
303        self.type = ptype                    # type: str
304        self.description = description       # type: str
305
306        # Length and length_control will be filled in once the complete
307        # parameter table is available.
308        self.length = 1                      # type: int
309        self.length_control = None           # type: Optional[str]
310        self.is_control = False              # type: bool
311
312        # TODO: need better control over whether a parameter is polydisperse
313        self.polydisperse = False            # type: bool
314        self.relative_pd = False             # type: bool
315
316        # choices are also set externally.
317        self.choices = []                    # type: List[str]
318
319    def as_definition(self):
320        # type: () -> str
321        """
322        Declare space for the variable in a parameter structure.
323
324        For example, the parameter thickness with length 3 will
325        return "double thickness[3];", with no spaces before and
326        no new line character afterward.
327        """
328        if self.length == 1:
329            return "double %s;"%self.id
330        else:
331            return "double %s[%d];"%(self.id, self.length)
332
333    def as_function_argument(self):
334        # type: () -> str
335        r"""
336        Declare the variable as a function argument.
337
338        For example, the parameter thickness with length 3 will
339        return "double \*thickness", with no spaces before and
340        no comma afterward.
341        """
342        if self.length == 1:
343            return "double %s"%self.id
344        else:
345            return "double *%s"%self.id
346
347    def as_call_reference(self, prefix=""):
348        # type: (str) -> str
349        """
350        Return *prefix* + parameter name.  For struct references, use "v."
351        as the prefix.
352        """
353        # Note: if the parameter is a struct type, then we will need to use
354        # &prefix+id.  For scalars and vectors we can just use prefix+id.
355        return prefix + self.id
356
357    def __str__(self):
358        # type: () -> str
359        return "<%s>"%self.name
360
361    def __repr__(self):
362        # type: () -> str
363        return "P<%s>"%self.name
364
365
366class ParameterTable(object):
367    """
368    ParameterTable manages the list of available parameters.
369
370    There are a couple of complications which mean that the list of parameters
371    for the kernel differs from the list of parameters that the user sees.
372
373    (1) Common parameters.  Scale and background are implicit to every model,
374    but are not passed to the kernel.
375
376    (2) Vector parameters.  Vector parameters are passed to the kernel as a
377    pointer to an array, e.g., thick[], but they are seen by the user as n
378    separate parameters thick1, thick2, ...
379
380    Therefore, the parameter table is organized by how it is expected to be
381    used. The following information is needed to set up the kernel functions:
382
383    * *kernel_parameters* is the list of parameters in the kernel parameter
384      table, with vector parameter p declared as p[].
385
386    * *iq_parameters* is the list of parameters to the Iq(q, ...) function,
387      with vector parameter p sent as p[].
388
389    * *form_volume_parameters* is the list of parameters to the form_volume(...)
390      function, with vector parameter p sent as p[].
391
392    Problem details, which sets up the polydispersity loops, requires the
393    following:
394
395    * *theta_offset* is the offset of the theta parameter in the kernel parameter
396      table, with vector parameters counted as n individual parameters
397      p1, p2, ..., or offset is -1 if there is no theta parameter.
398
399    * *max_pd* is the maximum number of polydisperse parameters, with vector
400      parameters counted as n individual parameters p1, p2, ...  Note that
401      this number is limited to sasmodels.modelinfo.MAX_PD.
402
403    * *npars* is the total number of parameters to the kernel, with vector
404      parameters counted as n individual parameters p1, p2, ...
405
406    * *call_parameters* is the complete list of parameters to the kernel,
407      including scale and background, with vector parameters recorded as
408      individual parameters p1, p2, ...
409
410    * *active_1d* is the set of names that may be polydisperse for 1d data
411
412    * *active_2d* is the set of names that may be polydisperse for 2d data
413
414    User parameters are the set of parameters visible to the user, including
415    the scale and background parameters that the kernel does not see.  User
416    parameters don't use vector notation, and instead use p1, p2, ...
417    """
418    # scale and background are implicit parameters
419    COMMON = [Parameter(*p) for p in COMMON_PARAMETERS]
420
421    def __init__(self, parameters):
422        # type: (List[Parameter]) -> None
423        self.kernel_parameters = parameters
424        self._set_vector_lengths()
425
426        self.npars = sum(p.length for p in self.kernel_parameters)
427        self.nmagnetic = sum(p.length for p in self.kernel_parameters
428                             if p.type == 'sld')
429        self.nvalues = 2 + self.npars
430        if self.nmagnetic:
431            self.nvalues += 3 + 3*self.nmagnetic
432
433        self.call_parameters = self._get_call_parameters()
434        self.defaults = self._get_defaults()
435        #self._name_table= dict((p.id, p) for p in parameters)
436
437        # Set the kernel parameters.  Assumes background and scale are the
438        # first two parameters in the parameter list, but these are not sent
439        # to the underlying kernel functions.
440        self.iq_parameters = [p for p in self.kernel_parameters
441                              if p.type not in ('orientation', 'magnetic')]
442        self.orientation_parameters = [p for p in self.kernel_parameters
443                                       if p.type == 'orientation']
444        self.form_volume_parameters = [p for p in self.kernel_parameters
445                                       if p.type == 'volume']
446
447        # Theta offset
448        offset = 0
449        for p in self.kernel_parameters:
450            if p.name == 'theta':
451                self.theta_offset = offset
452                break
453            offset += p.length
454        else:
455            self.theta_offset = -1
456
457        # number of polydisperse parameters
458        num_pd = sum(p.length for p in self.kernel_parameters if p.polydisperse)
459        # Don't use more polydisperse parameters than are available in the model
460        self.max_pd = min(num_pd, MAX_PD)
461
462        # true if has 2D parameters
463        self.has_2d = any(p.type in ('orientation', 'magnetic')
464                          for p in self.kernel_parameters)
465        self.is_asymmetric = any(p.name == 'psi' for p in self.kernel_parameters)
466        self.magnetism_index = [k for k, p in enumerate(self.call_parameters)
467                                if p.id.startswith('M0:')]
468
469        self.pd_1d = set(p.name for p in self.call_parameters
470                         if p.polydisperse and p.type not in ('orientation', 'magnetic'))
471        self.pd_2d = set(p.name for p in self.call_parameters if p.polydisperse)
472
473    def check_angles(self):
474        """
475        Check that orientation angles are theta, phi and possibly psi.
476        """
477        theta = phi = psi = -1
478        for k, p in enumerate(self.kernel_parameters):
479            if p.name == 'theta':
480                theta = k
481                if p.type != 'orientation':
482                    raise TypeError("theta must be an orientation parameter")
483            elif p.name == 'phi':
484                phi = k
485                if p.type != 'orientation':
486                    raise TypeError("phi must be an orientation parameter")
487            elif p.name == 'psi':
488                psi = k
489                if p.type != 'orientation':
490                    raise TypeError("psi must be an orientation parameter")
491            elif p.type == 'orientation':
492                raise TypeError("only theta, phi and psi can be orientation parameters")
493        if theta >= 0 and phi >= 0:
494            last_par = len(self.kernel_parameters) - 1
495            if phi != theta+1:
496                raise TypeError("phi must follow theta")
497            if psi >= 0 and psi != phi+1:
498                raise TypeError("psi must follow phi")
499            if (psi >= 0 and psi != last_par) or (psi < 0 and phi != last_par):
500                raise TypeError("orientation parameters must appear at the "
501                                "end of the parameter table")
502        elif theta >= 0 or phi >= 0 or psi >= 0:
503            raise TypeError("oriented shapes must have both theta and phi and maybe psi")
504
505    def __getitem__(self, key):
506        # Find the parameter definition
507        for par in self.call_parameters:
508            if par.name == key:
509                return par
510        raise KeyError("unknown parameter %r"%key)
511
512    def __contains__(self, key):
513        for par in self.call_parameters:
514            if par.name == key:
515                return True
516        return False
517
518    def _set_vector_lengths(self):
519        # type: () -> List[str]
520        """
521        Walk the list of kernel parameters, setting the length field of the
522        vector parameters from the upper limit of the reference parameter.
523
524        This needs to be done once the entire parameter table is available
525        since the reference may still be undefined when the parameter is
526        initially created.
527
528        Returns the list of control parameter names.
529
530        Note: This modifies the underlying parameter object.
531        """
532        # Sort out the length of the vector parameters such as thickness[n]
533        for p in self.kernel_parameters:
534            if p.length_control:
535                ref = self._get_ref(p)
536                ref.is_control = True
537                ref.polydisperse = False
538                low, high = ref.limits
539                if int(low) != low or int(high) != high or low < 0 or high > 20:
540                    raise ValueError("expected limits on %s to be within [0, 20]"
541                                     % ref.name)
542                p.length = int(high)
543
544    def _get_ref(self, p):
545        # type: (Parameter) -> Parameter
546        for ref in self.kernel_parameters:
547            if ref.id == p.length_control:
548                return ref
549        raise ValueError("no reference variable %r for %s"
550                         % (p.length_control, p.name))
551
552    def _get_defaults(self):
553        # type: () -> ParameterSet
554        """
555        Get a list of parameter defaults from the parameters.
556
557        Expands vector parameters into parameter id+number.
558        """
559        # Construct default values, including vector defaults
560        defaults = {}
561        for p in self.call_parameters:
562            if p.length == 1:
563                defaults[p.id] = p.default
564            else:
565                for k in range(1, p.length+1):
566                    defaults["%s%d"%(p.id, k)] = p.default
567        return defaults
568
569    def _get_call_parameters(self):
570        # type: () -> List[Parameter]
571        full_list = self.COMMON[:]
572        for p in self.kernel_parameters:
573            if p.length == 1:
574                full_list.append(p)
575            else:
576                for k in range(1, p.length+1):
577                    pk = Parameter(p.id+str(k), p.units, p.default,
578                                   p.limits, p.type, p.description)
579                    pk.polydisperse = p.polydisperse
580                    pk.relative_pd = p.relative_pd
581                    pk.choices = p.choices
582                    full_list.append(pk)
583
584        # Add the magnetic parameters to the end of the call parameter list.
585        if self.nmagnetic > 0:
586            full_list.extend([
587                Parameter('up:frac_i', '', 0., [0., 1.],
588                          'magnetic', 'fraction of spin up incident'),
589                Parameter('up:frac_f', '', 0., [0., 1.],
590                          'magnetic', 'fraction of spin up final'),
591                Parameter('up:angle', 'degrees', 0., [0., 360.],
592                          'magnetic', 'spin up angle'),
593            ])
594            slds = [p for p in full_list if p.type == 'sld']
595            for p in slds:
596                full_list.extend([
597                    Parameter('M0:'+p.id, '1e-6/Ang^2', 0., [-np.inf, np.inf],
598                              'magnetic', 'magnetic amplitude for '+p.description),
599                    Parameter('mtheta:'+p.id, 'degrees', 0., [-90., 90.],
600                              'magnetic', 'magnetic latitude for '+p.description),
601                    Parameter('mphi:'+p.id, 'degrees', 0., [-180., 180.],
602                              'magnetic', 'magnetic longitude for '+p.description),
603                ])
604        #print("call parameters", full_list)
605        return full_list
606
607    def user_parameters(self, pars, is2d=True):
608        # type: (Dict[str, float], bool) -> List[Parameter]
609        """
610        Return the list of parameters for the given data type.
611
612        Vector parameters are expanded in place.  If multiple parameters
613        share the same vector length, then the parameters will be interleaved
614        in the result.  The control parameters come first.  For example,
615        if the parameter table is ordered as::
616
617            sld_core
618            sld_shell[num_shells]
619            sld_solvent
620            thickness[num_shells]
621            num_shells
622
623        and *pars[num_shells]=2* then the returned list will be::
624
625            num_shells
626            scale
627            background
628            sld_core
629            sld_shell1
630            thickness1
631            sld_shell2
632            thickness2
633            sld_solvent
634
635        Note that shell/thickness pairs are grouped together in the result
636        even though they were not grouped in the incoming table.  The control
637        parameter is always returned first since the GUI will want to set it
638        early, and rerender the table when it is changed.
639
640        Parameters marked as sld will automatically have a set of associated
641        magnetic parameters (m0:p, mtheta:p, mphi:p), as well as polarization
642        information (up:theta, up:frac_i, up:frac_f).
643        """
644        # control parameters go first
645        control = [p for p in self.kernel_parameters if p.is_control]
646
647        # Gather entries such as name[n] into groups of the same n
648        dependent = {} # type: Dict[str, List[Parameter]]
649        dependent.update((p.id, []) for p in control)
650        for p in self.kernel_parameters:
651            if p.length_control is not None:
652                dependent[p.length_control].append(p)
653
654        # Gather entries such as name[4] into groups of the same length
655        fixed_length = {}  # type: Dict[int, List[Parameter]]
656        for p in self.kernel_parameters:
657            if p.length > 1 and p.length_control is None:
658                fixed_length.setdefault(p.length, []).append(p)
659
660        # Using the call_parameters table, we already have expanded forms
661        # for each of the vector parameters; put them in a lookup table
662        # Note: p.id and p.name are currently identical for the call parameters
663        expanded_pars = dict((p.id, p) for p in self.call_parameters)
664
665        def append_group(name):
666            """add the named parameter, and related magnetic parameters if any"""
667            result.append(expanded_pars[name])
668            if is2d:
669                for tag in 'M0:', 'mtheta:', 'mphi:':
670                    if tag+name in expanded_pars:
671                        result.append(expanded_pars[tag+name])
672
673        # Gather the user parameters in order
674        result = control + self.COMMON
675        for p in self.kernel_parameters:
676            if not is2d and p.type in ('orientation', 'magnetic'):
677                pass
678            elif p.is_control:
679                pass # already added
680            elif p.length_control is not None:
681                table = dependent.get(p.length_control, [])
682                if table:
683                    # look up length from incoming parameters
684                    table_length = int(pars.get(p.length_control, p.length))
685                    del dependent[p.length_control] # first entry seen
686                    for k in range(1, table_length+1):
687                        for entry in table:
688                            append_group(entry.id+str(k))
689                else:
690                    pass # already processed all entries
691            elif p.length > 1:
692                table = fixed_length.get(p.length, [])
693                if table:
694                    table_length = p.length
695                    del fixed_length[p.length]
696                    for k in range(1, table_length+1):
697                        for entry in table:
698                            append_group(entry.id+str(k))
699                else:
700                    pass # already processed all entries
701            else:
702                append_group(p.id)
703
704        if is2d and 'up:angle' in expanded_pars:
705            result.extend([
706                expanded_pars['up:frac_i'],
707                expanded_pars['up:frac_f'],
708                expanded_pars['up:angle'],
709            ])
710
711        return result
712
713def isstr(x):
714    # type: (Any) -> bool
715    """
716    Return True if the object is a string.
717    """
718    # TODO: 2-3 compatible tests for str, including unicode strings
719    return isinstance(x, str)
720
721
722#: Set of variables defined in the model that might contain C code
723C_SYMBOLS = ['Imagnetic', 'Iq', 'Iqxy', 'Iqac', 'Iqabc', 'form_volume', 'c_code']
724
725def _find_source_lines(model_info, kernel_module):
726    # type: (ModelInfo, ModuleType) -> None
727    """
728    Identify the location of the C source inside the model definition file.
729
730    This code runs through the source of the kernel module looking for lines
731    that contain C code (because it is a c function definition).  Clearly
732    there are all sorts of reasons why this might not work (e.g., code
733    commented out in a triple-quoted line block, code built using string
734    concatenation, code defined in the branch of an 'if' block, code imported
735    from another file), but it should work properly in the 95% case, and for
736    the remainder, getting the incorrect line number will merely be
737    inconvenient.
738    """
739    # Only need line numbers if we are creating a C module and the C symbols
740    # are defined.
741    if (callable(model_info.Iq)
742            or not any(hasattr(model_info, s) for s in C_SYMBOLS)):
743        return
744
745    # load the module source if we can
746    try:
747        source = inspect.getsource(kernel_module)
748    except IOError:
749        return
750
751    # look for symbol at the start of the line
752    for lineno, line in enumerate(source.split('\n')):
753        for name in C_SYMBOLS:
754            if line.startswith(name):
755                # Add 1 since some compilers complain about "#line 0"
756                model_info.lineno[name] = lineno + 1
757                break
758
759def make_model_info(kernel_module):
760    # type: (module) -> ModelInfo
761    """
762    Extract the model definition from the loaded kernel module.
763
764    Fill in default values for parts of the module that are not provided.
765
766    Note: vectorized Iq and Iqac/Iqabc functions will be created for python
767    models when the model is first called, not when the model is loaded.
768    """
769    if hasattr(kernel_module, "model_info"):
770        # Custom sum/multi models
771        return kernel_module.model_info
772    info = ModelInfo()
773    #print("make parameter table", kernel_module.parameters)
774    parameters = make_parameter_table(getattr(kernel_module, 'parameters', []))
775    demo = expand_pars(parameters, getattr(kernel_module, 'demo', None))
776    filename = abspath(kernel_module.__file__).replace('.pyc', '.py')
777    kernel_id = splitext(basename(filename))[0]
778    name = getattr(kernel_module, 'name', None)
779    if name is None:
780        name = " ".join(w.capitalize() for w in kernel_id.split('_'))
781
782    info.id = kernel_id  # string used to load the kernel
783    info.filename = filename
784    info.name = name
785    info.title = getattr(kernel_module, 'title', name+" model")
786    info.description = getattr(kernel_module, 'description', 'no description')
787    info.parameters = parameters
788    info.demo = demo
789    info.composition = None
790    info.docs = kernel_module.__doc__
791    info.category = getattr(kernel_module, 'category', None)
792    info.structure_factor = getattr(kernel_module, 'structure_factor', False)
793    info.profile_axes = getattr(kernel_module, 'profile_axes', ['x', 'y'])
794    info.source = getattr(kernel_module, 'source', [])
795    info.c_code = getattr(kernel_module, 'c_code', None)
796    # TODO: check the structure of the tests
797    info.tests = getattr(kernel_module, 'tests', [])
798    info.ER = getattr(kernel_module, 'ER', None) # type: ignore
799    info.VR = getattr(kernel_module, 'VR', None) # type: ignore
800    info.form_volume = getattr(kernel_module, 'form_volume', None) # type: ignore
801    info.Iq = getattr(kernel_module, 'Iq', None) # type: ignore
802    info.Iqxy = getattr(kernel_module, 'Iqxy', None) # type: ignore
803    info.Iqac = getattr(kernel_module, 'Iqac', None) # type: ignore
804    info.Iqabc = getattr(kernel_module, 'Iqabc', None) # type: ignore
805    info.Imagnetic = getattr(kernel_module, 'Imagnetic', None) # type: ignore
806    info.profile = getattr(kernel_module, 'profile', None) # type: ignore
807    info.sesans = getattr(kernel_module, 'sesans', None) # type: ignore
808    # Default single and opencl to True for C models.  Python models have callable Iq.
809    info.opencl = getattr(kernel_module, 'opencl', not callable(info.Iq))
810    info.single = getattr(kernel_module, 'single', not callable(info.Iq))
811    info.random = getattr(kernel_module, 'random', None)
812
813    # multiplicity info
814    control_pars = [p.id for p in parameters.kernel_parameters if p.is_control]
815    default_control = control_pars[0] if control_pars else None
816    info.control = getattr(kernel_module, 'control', default_control)
817    info.hidden = getattr(kernel_module, 'hidden', None) # type: ignore
818
819    if callable(info.Iq) and parameters.has_2d:
820        raise ValueError("oriented python models not supported")
821
822    info.lineno = {}
823    _find_source_lines(info, kernel_module)
824
825    return info
826
827class ModelInfo(object):
828    """
829    Interpret the model definition file, categorizing the parameters.
830
831    The module can be loaded with a normal python import statement if you
832    know which module you need, or with __import__('sasmodels.model.'+name)
833    if the name is in a string.
834
835    The structure should be mostly static, other than the delayed definition
836    of *Iq*, *Iqac* and *Iqabc* if they need to be defined.
837    """
838    #: Full path to the file defining the kernel, if any.
839    filename = None         # type: Optional[str]
840    #: Id of the kernel used to load it from the filesystem.
841    id = None               # type: str
842    #: Display name of the model, which defaults to the model id but with
843    #: capitalization of the parts so for example core_shell defaults to
844    #: "Core Shell".
845    name = None             # type: str
846    #: Short description of the model.
847    title = None            # type: str
848    #: Long description of the model.
849    description = None      # type: str
850    #: Model parameter table. Parameters are defined using a list of parameter
851    #: definitions, each of which is contains parameter name, units,
852    #: default value, limits, type and description.  See :class:`Parameter`
853    #: for details on the individual parameters.  The parameters are gathered
854    #: into a :class:`ParameterTable`, which provides various views into the
855    #: parameter list.
856    parameters = None       # type: ParameterTable
857    #: Demo parameters as a *parameter:value* map used as the default values
858    #: for :mod:`compare`.  Any parameters not set in *demo* will use the
859    #: defaults from the parameter table.  That means no polydispersity, and
860    #: in the case of multiplicity models, a minimal model with no interesting
861    #: scattering.
862    demo = None             # type: Dict[str, float]
863    #: Composition is None if this is an independent model, or it is a
864    #: tuple with comoposition type ('product' or 'misture') and a list of
865    #: :class:`ModelInfo` blocks for the composed objects.  This allows us
866    #: to rebuild a complete mixture or product model from the info block.
867    #: *composition* is not given in the model definition file, but instead
868    #: arises when the model is constructed using names such as
869    #: *sphere*hardsphere* or *cylinder+sphere*.
870    composition = None      # type: Optional[Tuple[str, List[ModelInfo]]]
871    #: Name of the control parameter for a variant model such as :ref:`rpa`.
872    #: The *control* parameter should appear in the parameter table, with
873    #: limits defined as *[CASES]*, for case names such as
874    #: *CASES = ["diblock copolymer", "triblock copolymer", ...]*.
875    #: This should give *limits=[[case1, case2, ...]]*, but the
876    #: model loader translates this to *limits=[0, len(CASES)-1]*, and adds
877    #: *choices=CASES* to the :class:`Parameter` definition. Note that
878    #: models can use a list of cases as a parameter without it being a
879    #: control parameter.  Either way, the parameter is sent to the model
880    #: evaluator as *float(choice_num)*, where choices are numbered from 0.
881    #: See also :attr:`hidden`.
882    control = None          # type: str
883    #: Different variants require different parameters.  In order to show
884    #: just the parameters needed for the variant selected by :attr:`control`,
885    #: you should provide a function *hidden(control) -> set(['a', 'b', ...])*
886    #: indicating which parameters need to be hidden.  For multiplicity
887    #: models, you need to use the complete name of the parameter, including
888    #: its number.  So for example, if variant "a" uses only *sld1* and *sld2*,
889    #: then *sld3*, *sld4* and *sld5* of multiplicity parameter *sld[5]*
890    #: should be in the hidden set.
891    hidden = None           # type: Optional[Callable[[int], Set[str]]]
892    #: Doc string from the top of the model file.  This should be formatted
893    #: using ReStructuredText format, with latex markup in ".. math"
894    #: environments, or in dollar signs.  This will be automatically
895    #: extracted to a .rst file by :func:`generate.make_docs`, then
896    #: converted to HTML or PDF by Sphinx.
897    docs = None             # type: str
898    #: Location of the model description in the documentation.  This takes the
899    #: form of "section" or "section:subsection".  So for example,
900    #: :ref:`porod` uses *category="shape-independent"* so it is in the
901    #: :ref:`shape-independent` section whereas
902    #: :ref:`capped-cylinder` uses: *category="shape:cylinder"*, which puts
903    #: it in the :ref:`shape-cylinder` section.
904    category = None         # type: Optional[str]
905    #: True if the model can be computed accurately with single precision.
906    #: This is True by default, but models such as :ref:`bcc-paracrystal` set
907    #: it to False because they require double precision calculations.
908    single = None           # type: bool
909    #: True if the model can be run as an opencl model.  If for some reason
910    #: the model cannot be run in opencl (e.g., because the model passes
911    #: functions by reference), then set this to false.
912    opencl = None           # type: bool
913    #: True if the model is a structure factor used to model the interaction
914    #: between form factor models.  This will default to False if it is not
915    #: provided in the file.
916    structure_factor = None # type: bool
917    #: List of C source files used to define the model.  The source files
918    #: should define the *Iq* function, and possibly *Iqac* or *Iqabc* if the
919    #: model defines orientation parameters. Files containing the most basic
920    #: functions must appear first in the list, followed by the files that
921    #: use those functions.  Form factors are indicated by providing
922    #: an :attr:`ER` function.
923    source = None           # type: List[str]
924    #: The set of tests that must pass.  The format of the tests is described
925    #: in :mod:`model_test`.
926    tests = None            # type: List[TestCondition]
927    #: Returns the effective radius of the model given its volume parameters.
928    #: The presence of *ER* indicates that the model is a form factor model
929    #: that may be used together with a structure factor to form an implicit
930    #: multiplication model.
931    #:
932    #: The parameters to the *ER* function must be marked with type *volume*.
933    #: in the parameter table.  They will appear in the same order as they
934    #: do in the table.  The values passed to *ER* will be vectors, with one
935    #: value for each polydispersity condition.  For example, if the model
936    #: is polydisperse over both length and radius, then both length and
937    #: radius will have the same number of values in the vector, with one
938    #: value for each *length X radius*.  If only *radius* is polydisperse,
939    #: then the value for *length* will be repeated once for each value of
940    #: *radius*.  The *ER* function should return one effective radius for
941    #: each parameter set.  Multiplicity parameters will be received as
942    #: arrays, with one row per polydispersity condition.
943    ER = None               # type: Optional[Callable[[np.ndarray], np.ndarray]]
944    #: Returns the occupied volume and the total volume for each parameter set.
945    #: See :attr:`ER` for details on the parameters.
946    VR = None               # type: Optional[Callable[[np.ndarray], Tuple[np.ndarray, np.ndarray]]]
947    #: Arbitrary C code containing supporting functions, etc., to be inserted
948    #: after everything in source.  This can include Iq and Iqxy functions with
949    #: the full function signature, including all parameters.
950    c_code = None
951    #: Returns the form volume for python-based models.  Form volume is needed
952    #: for volume normalization in the polydispersity integral.  If no
953    #: parameters are *volume* parameters, then form volume is not needed.
954    #: For C-based models, (with :attr:`sources` defined, or with :attr:`Iq`
955    #: defined using a string containing C code), form_volume must also be
956    #: C code, either defined as a string, or in the sources.
957    form_volume = None      # type: Union[None, str, Callable[[np.ndarray], float]]
958    #: Returns *I(q, a, b, ...)* for parameters *a*, *b*, etc. defined
959    #: by the parameter table.  *Iq* can be defined as a python function, or
960    #: as a C function.  If it is defined in C, then set *Iq* to the body of
961    #: the C function, including the return statement.  This function takes
962    #: values for *q* and each of the parameters as separate *double* values
963    #: (which may be converted to float or long double by sasmodels).  All
964    #: source code files listed in :attr:`sources` will be loaded before the
965    #: *Iq* function is defined.  If *Iq* is not present, then sources should
966    #: define *static double Iq(double q, double a, double b, ...)* which
967    #: will return *I(q, a, b, ...)*.  Multiplicity parameters are sent as
968    #: pointers to doubles.  Constants in floating point expressions should
969    #: include the decimal point. See :mod:`generate` for more details.
970    Iq = None               # type: Union[None, str, Callable[[np.ndarray], np.ndarray]]
971    #: Returns *I(qab, qc, a, b, ...)*.  The interface follows :attr:`Iq`.
972    Iqac = None             # type: Union[None, str, Callable[[np.ndarray], np.ndarray]]
973    #: Returns *I(qa, qb, qc, a, b, ...)*.  The interface follows :attr:`Iq`.
974    Iqabc = None            # type: Union[None, str, Callable[[np.ndarray], np.ndarray]]
975    #: Returns *I(qx, qy, a, b, ...)*.  The interface follows :attr:`Iq`.
976    Imagnetic = None        # type: Union[None, str, Callable[[np.ndarray], np.ndarray]]
977    #: Returns a model profile curve *x, y*.  If *profile* is defined, this
978    #: curve will appear in response to the *Show* button in SasView.  Use
979    #: :attr:`profile_axes` to set the axis labels.  Note that *y* values
980    #: will be scaled by 1e6 before plotting.
981    profile = None          # type: Optional[Callable[[np.ndarray], None]]
982    #: Axis labels for the :attr:`profile` plot.  The default is *['x', 'y']*.
983    #: Only the *x* component is used for now.
984    profile_axes = None     # type: Tuple[str, str]
985    #: Returns *sesans(z, a, b, ...)* for models which can directly compute
986    #: the SESANS correlation function.  Note: not currently implemented.
987    sesans = None           # type: Optional[Callable[[np.ndarray], np.ndarray]]
988    #: Returns a random parameter set for the model
989    random = None           # type: Optional[Callable[[], Dict[str, float]]]
990    #: Line numbers for symbols defining C code
991    lineno = None           # type: Dict[str, int]
992
993    def __init__(self):
994        # type: () -> None
995        pass
996
997    def get_hidden_parameters(self, control):
998        """
999        Returns the set of hidden parameters for the model.  *control* is the
1000        value of the control parameter.  Note that multiplicity models have
1001        an implicit control parameter, which is the parameter that controls
1002        the multiplicity.
1003        """
1004        if self.hidden is not None:
1005            hidden = self.hidden(control)
1006        else:
1007            controls = [p for p in self.parameters.kernel_parameters
1008                        if p.is_control]
1009            if len(controls) != 1:
1010                raise ValueError("more than one control parameter")
1011            hidden = set(p.id+str(k)
1012                         for p in self.parameters.kernel_parameters
1013                         for k in range(control+1, p.length+1)
1014                         if p.length > 1)
1015        return hidden
Note: See TracBrowser for help on using the repository browser.