source: sasmodels/sasmodels/modelinfo.py @ 9c44b7b

core_shell_microgelscostrafo411magnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 9c44b7b was 9c44b7b, checked in by Paul Kienzle <pkienzle@…>, 7 years ago

Merge branch 'master' into ticket-843

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