source: sasmodels/sasmodels/modelinfo.py @ 6592f56

core_shell_microgelscostrafo411magnetic_modelrelease_v0.94release_v0.95ticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 6592f56 was 8407d8c, checked in by wojciech, 8 years ago

Changed gpu flag to opencl as it seems more appropritae to what code is doing

  • Property mode set to 100644
File size: 41.2 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, (0.0, 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.single = getattr(kernel_module, 'single', True)
733    info.opencl = getattr(kernel_module, 'opencl', True)
734    info.structure_factor = getattr(kernel_module, 'structure_factor', False)
735    info.profile_axes = getattr(kernel_module, 'profile_axes', ['x', 'y'])
736    info.source = getattr(kernel_module, 'source', [])
737    # TODO: check the structure of the tests
738    info.tests = getattr(kernel_module, 'tests', [])
739    info.ER = getattr(kernel_module, 'ER', None) # type: ignore
740    info.VR = getattr(kernel_module, 'VR', None) # type: ignore
741    info.form_volume = getattr(kernel_module, 'form_volume', None) # type: ignore
742    info.Iq = getattr(kernel_module, 'Iq', None) # type: ignore
743    info.Iqxy = getattr(kernel_module, 'Iqxy', None) # type: ignore
744    info.Imagnetic = getattr(kernel_module, 'Imagnetic', None) # type: ignore
745    info.profile = getattr(kernel_module, 'profile', None) # type: ignore
746    info.sesans = getattr(kernel_module, 'sesans', None) # type: ignore
747
748    # multiplicity info
749    control_pars = [p.id for p in parameters.kernel_parameters if p.is_control]
750    default_control = control_pars[0] if control_pars else None
751    info.control = getattr(kernel_module, 'control', default_control)
752    info.hidden = getattr(kernel_module, 'hidden', None) # type: ignore
753
754    _find_source_lines(info, kernel_module)
755
756    return info
757
758class ModelInfo(object):
759    """
760    Interpret the model definition file, categorizing the parameters.
761
762    The module can be loaded with a normal python import statement if you
763    know which module you need, or with __import__('sasmodels.model.'+name)
764    if the name is in a string.
765
766    The structure should be mostly static, other than the delayed definition
767    of *Iq* and *Iqxy* if they need to be defined.
768    """
769    #: Full path to the file defining the kernel, if any.
770    filename = None         # type: Optiona[str]
771    #: Id of the kernel used to load it from the filesystem.
772    id = None               # type: str
773    #: Display name of the model, which defaults to the model id but with
774    #: capitalization of the parts so for example core_shell defaults to
775    #: "Core Shell".
776    name = None             # type: str
777    #: Short description of the model.
778    title = None            # type: str
779    #: Long description of the model.
780    description = None      # type: str
781    #: Model parameter table. Parameters are defined using a list of parameter
782    #: definitions, each of which is contains parameter name, units,
783    #: default value, limits, type and description.  See :class:`Parameter`
784    #: for details on the individual parameters.  The parameters are gathered
785    #: into a :class:`ParameterTable`, which provides various views into the
786    #: parameter list.
787    parameters = None       # type: ParameterTable
788    #: Demo parameters as a *parameter:value* map used as the default values
789    #: for :mod:`compare`.  Any parameters not set in *demo* will use the
790    #: defaults from the parameter table.  That means no polydispersity, and
791    #: in the case of multiplicity models, a minimal model with no interesting
792    #: scattering.
793    demo = None             # type: Dict[str, float]
794    #: Composition is None if this is an independent model, or it is a
795    #: tuple with comoposition type ('product' or 'misture') and a list of
796    #: :class:`ModelInfo` blocks for the composed objects.  This allows us
797    #: to rebuild a complete mixture or product model from the info block.
798    #: *composition* is not given in the model definition file, but instead
799    #: arises when the model is constructed using names such as
800    #: *sphere*hardsphere* or *cylinder+sphere*.
801    composition = None      # type: Optional[Tuple[str, List[ModelInfo]]]
802    #: Name of the control parameter for a variant model such as :ref:`rpa`.
803    #: The *control* parameter should appear in the parameter table, with
804    #: limits defined as *[CASES]*, for case names such as
805    #: *CASES = ["diblock copolymer", "triblock copolymer", ...]*.
806    #: This should give *limits=[[case1, case2, ...]]*, but the
807    #: model loader translates this to *limits=[0, len(CASES)-1]*, and adds
808    #: *choices=CASES* to the :class:`Parameter` definition. Note that
809    #: models can use a list of cases as a parameter without it being a
810    #: control parameter.  Either way, the parameter is sent to the model
811    #: evaluator as *float(choice_num)*, where choices are numbered from 0.
812    #: See also :attr:`hidden`.
813    control = None          # type: str
814    #: Different variants require different parameters.  In order to show
815    #: just the parameters needed for the variant selected by :attr:`control`,
816    #: you should provide a function *hidden(control) -> set(['a', 'b', ...])*
817    #: indicating which parameters need to be hidden.  For multiplicity
818    #: models, you need to use the complete name of the parameter, including
819    #: its number.  So for example, if variant "a" uses only *sld1* and *sld2*,
820    #: then *sld3*, *sld4* and *sld5* of multiplicity parameter *sld[5]*
821    #: should be in the hidden set.
822    hidden = None           # type: Optional[Callable[[int], Set[str]]]
823    #: Doc string from the top of the model file.  This should be formatted
824    #: using ReStructuredText format, with latex markup in ".. math"
825    #: environments, or in dollar signs.  This will be automatically
826    #: extracted to a .rst file by :func:`generate.make_docs`, then
827    #: converted to HTML or PDF by Sphinx.
828    docs = None             # type: str
829    #: Location of the model description in the documentation.  This takes the
830    #: form of "section" or "section:subsection".  So for example,
831    #: :ref:`porod` uses *category="shape-independent"* so it is in the
832    #: :ref:`shape-independent` section whereas
833    #: :ref:`capped-cylinder` uses: *category="shape:cylinder"*, which puts
834    #: it in the :ref:`shape-cylinder` section.
835    category = None         # type: Optional[str]
836    #: True if the model can be computed accurately with single precision.
837    #: This is True by default, but models such as :ref:`bcc-paracrystal` set
838    #: it to False because they require double precision calculations.
839    single = None           # type: bool
840    #: True if the model is a structure factor used to model the interaction
841    #: between form factor models.  This will default to False if it is not
842    #: provided in the file.
843    structure_factor = None # type: bool
844    #: List of C source files used to define the model.  The source files
845    #: should define the *Iq* function, and possibly *Iqxy*, though a default
846    #: *Iqxy = Iq(sqrt(qx**2+qy**2)* will be created if no *Iqxy* is provided.
847    #: Files containing the most basic functions must appear first in the list,
848    #: followed by the files that use those functions.  Form factors are
849    #: indicated by providing a :attr:`ER` function.
850    source = None           # type: List[str]
851    #: The set of tests that must pass.  The format of the tests is described
852    #: in :mod:`model_test`.
853    tests = None            # type: List[TestCondition]
854    #: Returns the effective radius of the model given its volume parameters.
855    #: The presence of *ER* indicates that the model is a form factor model
856    #: that may be used together with a structure factor to form an implicit
857    #: multiplication model.
858    #:
859    #: The parameters to the *ER* function must be marked with type *volume*.
860    #: in the parameter table.  They will appear in the same order as they
861    #: do in the table.  The values passed to *ER* will be vectors, with one
862    #: value for each polydispersity condition.  For example, if the model
863    #: is polydisperse over both length and radius, then both length and
864    #: radius will have the same number of values in the vector, with one
865    #: value for each *length X radius*.  If only *radius* is polydisperse,
866    #: then the value for *length* will be repeated once for each value of
867    #: *radius*.  The *ER* function should return one effective radius for
868    #: each parameter set.  Multiplicity parameters will be received as
869    #: arrays, with one row per polydispersity condition.
870    ER = None               # type: Optional[Callable[[np.ndarray], np.ndarray]]
871    #: Returns the occupied volume and the total volume for each parameter set.
872    #: See :attr:`ER` for details on the parameters.
873    VR = None               # type: Optional[Callable[[np.ndarray], Tuple[np.ndarray, np.ndarray]]]
874    #: Returns the form volume for python-based models.  Form volume is needed
875    #: for volume normalization in the polydispersity integral.  If no
876    #: parameters are *volume* parameters, then form volume is not needed.
877    #: For C-based models, (with :attr:`sources` defined, or with :attr:`Iq`
878    #: defined using a string containing C code), form_volume must also be
879    #: C code, either defined as a string, or in the sources.
880    form_volume = None      # type: Union[None, str, Callable[[np.ndarray], float]]
881    #: Returns *I(q, a, b, ...)* for parameters *a*, *b*, etc. defined
882    #: by the parameter table.  *Iq* can be defined as a python function, or
883    #: as a C function.  If it is defined in C, then set *Iq* to the body of
884    #: the C function, including the return statement.  This function takes
885    #: values for *q* and each of the parameters as separate *double* values
886    #: (which may be converted to float or long double by sasmodels).  All
887    #: source code files listed in :attr:`sources` will be loaded before the
888    #: *Iq* function is defined.  If *Iq* is not present, then sources should
889    #: define *static double Iq(double q, double a, double b, ...)* which
890    #: will return *I(q, a, b, ...)*.  Multiplicity parameters are sent as
891    #: pointers to doubles.  Constants in floating point expressions should
892    #: include the decimal point. See :mod:`generate` for more details.
893    Iq = None               # type: Union[None, str, Callable[[np.ndarray], np.ndarray]]
894    #: Returns *I(qx, qy, a, b, ...)*.  The interface follows :attr:`Iq`.
895    Iqxy = None             # type: Union[None, str, Callable[[np.ndarray], np.ndarray]]
896    #: Returns *I(qx, qy, a, b, ...)*.  The interface follows :attr:`Iq`.
897    Imagnetic = None        # type: Union[None, str, Callable[[np.ndarray], np.ndarray]]
898    #: Returns a model profile curve *x, y*.  If *profile* is defined, this
899    #: curve will appear in response to the *Show* button in SasView.  Use
900    #: :attr:`profile_axes` to set the axis labels.  Note that *y* values
901    #: will be scaled by 1e6 before plotting.
902    profile = None          # type: Optional[Callable[[np.ndarray], None]]
903    #: Axis labels for the :attr:`profile` plot.  The default is *['x', 'y']*.
904    #: Only the *x* component is used for now.
905    profile_axes = None     # type: Tuple[str, str]
906    #: Returns *sesans(z, a, b, ...)* for models which can directly compute
907    #: the SESANS correlation function.  Note: not currently implemented.
908    sesans = None           # type: Optional[Callable[[np.ndarray], np.ndarray]]
909
910    # line numbers within the python file for bits of C source, if defined
911    # NB: some compilers fail with a "#line 0" directive, so default to 1.
912    _Imagnetic_line = 1
913    _Iqxy_line = 1
914    _Iq_line = 1
915    _form_volume_line = 1
916
917
918    def __init__(self):
919        # type: () -> None
920        pass
921
922    def get_hidden_parameters(self, control):
923        """
924        Returns the set of hidden parameters for the model.  *control* is the
925        value of the control parameter.  Note that multiplicity models have
926        an implicit control parameter, which is the parameter that controls
927        the multiplicity.
928        """
929        if self.hidden is not None:
930            hidden = self.hidden(control)
931        else:
932            controls = [p for p in self.parameters.kernel_parameters
933                        if p.is_control]
934            if len(controls) != 1:
935                raise ValueError("more than one control parameter")
936            hidden = set(p.id+str(k)
937                         for p in self.parameters.kernel_parameters
938                         for k in range(control+1, p.length+1)
939                         if p.length > 1)
940        return hidden
Note: See TracBrowser for help on using the repository browser.