source: sasmodels/sasmodels/modelinfo.py @ 5124c969

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

allow multicompare to select opencl+single+1d

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