source: sasmodels/sasmodels/generate.py @ 5ceb7d0

core_shell_microgelscostrafo411magnetic_modelrelease_v0.94release_v0.95ticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 5ceb7d0 was 5ceb7d0, checked in by smk78, 7 years ago

Unchanged

  • Property mode set to 100644
File size: 27.5 KB
Line 
1"""
2SAS model constructor.
3
4Small angle scattering models are defined by a set of kernel functions:
5
6    *Iq(q, p1, p2, ...)* returns the scattering at q for a form with
7    particular dimensions averaged over all orientations.
8
9    *Iqxy(qx, qy, p1, p2, ...)* returns the scattering at qx, qy for a form
10    with particular dimensions for a single orientation.
11
12    *Imagnetic(qx, qy, result[], p1, p2, ...)* returns the scattering for the
13    polarized neutron spin states (up-up, up-down, down-up, down-down) for
14    a form with particular dimensions for a single orientation.
15
16    *form_volume(p1, p2, ...)* returns the volume of the form with particular
17    dimension.
18
19    *ER(p1, p2, ...)* returns the effective radius of the form with
20    particular dimensions.
21
22    *VR(p1, p2, ...)* returns the volume ratio for core-shell style forms.
23
24These functions are defined in a kernel module .py script and an associated
25set of .c files.  The model constructor will use them to create models with
26polydispersity across volume and orientation parameters, and provide
27scale and background parameters for each model.
28
29*Iq*, *Iqxy*, *Imagnetic* and *form_volume* should be stylized C-99
30functions written for OpenCL.  All functions need prototype declarations
31even if the are defined before they are used.  OpenCL does not support
32*#include* preprocessor directives, so instead the list of includes needs
33to be given as part of the metadata in the kernel module definition.
34The included files should be listed using a path relative to the kernel
35module, or if using "lib/file.c" if it is one of the standard includes
36provided with the sasmodels source.  The includes need to be listed in
37order so that functions are defined before they are used.
38
39Floating point values should be declared as *double*.  For single precision
40calculations, *double* will be replaced by *float*.  The single precision
41conversion will also tag floating point constants with "f" to make them
42single precision constants.  When using integral values in floating point
43expressions, they should be expressed as floating point values by including
44a decimal point.  This includes 0., 1. and 2.
45
46OpenCL has a *sincos* function which can improve performance when both
47the *sin* and *cos* values are needed for a particular argument.  Since
48this function does not exist in C99, all use of *sincos* should be
49replaced by the macro *SINCOS(value, sn, cn)* where *sn* and *cn* are
50previously declared *double* variables.  When compiled for systems without
51OpenCL, *SINCOS* will be replaced by *sin* and *cos* calls.   If *value* is
52an expression, it will appear twice in this case; whether or not it will be
53evaluated twice depends on the quality of the compiler.
54
55If the input parameters are invalid, the scattering calculator should
56return a negative number. Particularly with polydispersity, there are
57some sets of shape parameters which lead to nonsensical forms, such
58as a capped cylinder where the cap radius is smaller than the
59cylinder radius.  The polydispersity calculation will ignore these points,
60effectively chopping the parameter weight distributions at the boundary
61of the infeasible region.  The resulting scattering will be set to
62background.  This will work correctly even when polydispersity is off.
63
64*ER* and *VR* are python functions which operate on parameter vectors.
65The constructor code will generate the necessary vectors for computing
66them with the desired polydispersity.
67
68The available kernel parameters are defined as a list, with each parameter
69defined as a sublist with the following elements:
70
71    *name* is the name that will be used in the call to the kernel
72    function and the name that will be displayed to the user.  Names
73    should be lower case, with words separated by underscore.  If
74    acronyms are used, the whole acronym should be upper case.
75
76    *units* should be one of *degrees* for angles, *Ang* for lengths,
77    *1e-6/Ang^2* for SLDs.
78
79    *default value* will be the initial value for  the model when it
80    is selected, or when an initial value is not otherwise specified.
81
82    [*lb*, *ub*] are the hard limits on the parameter value, used to limit
83    the polydispersity density function.  In the fit, the parameter limits
84    given to the fit are the limits  on the central value of the parameter.
85    If there is polydispersity, it will evaluate parameter values outside
86    the fit limits, but not outside the hard limits specified in the model.
87    If there are no limits, use +/-inf imported from numpy.
88
89    *type* indicates how the parameter will be used.  "volume" parameters
90    will be used in all functions.  "orientation" parameters will be used
91    in *Iqxy* and *Imagnetic*.  "magnetic* parameters will be used in
92    *Imagnetic* only.  If *type* is the empty string, the parameter will
93    be used in all of *Iq*, *Iqxy* and *Imagnetic*.
94
95    *description* is a short description of the parameter.  This will
96    be displayed in the parameter table and used as a tool tip for the
97    parameter value in the user interface.
98
99The kernel module must set variables defining the kernel meta data:
100
101    *id* is an implicit variable formed from the filename.  It will be
102    a valid python identifier, and will be used as the reference into
103    the html documentation, with '_' replaced by '-'.
104
105    *name* is the model name as displayed to the user.  If it is missing,
106    it will be constructed from the id.
107
108    *title* is a short description of the model, suitable for a tool tip,
109    or a one line model summary in a table of models.
110
111    *description* is an extended description of the model to be displayed
112    while the model parameters are being edited.
113
114    *parameters* is the list of parameters.  Parameters in the kernel
115    functions must appear in the same order as they appear in the
116    parameters list.  Two additional parameters, *scale* and *background*
117    are added to the beginning of the parameter list.  They will show up
118    in the documentation as model parameters, but they are never sent to
119    the kernel functions.
120
121    *category* is the default category for the model.  Models in the
122    *structure-factor* category do not have *scale* and *background*
123    added.
124
125    *source* is the list of C-99 source files that must be joined to
126    create the OpenCL kernel functions.  The files defining the functions
127    need to be listed before the files which use the functions.
128
129    *ER* is a python function defining the effective radius.  If it is
130    not present, the effective radius is 0.
131
132    *VR* is a python function defining the volume ratio.  If it is not
133    present, the volume ratio is 1.
134
135    *form_volume*, *Iq*, *Iqxy*, *Imagnetic* are strings containing the
136    C source code for the body of the volume, Iq, and Iqxy functions
137    respectively.  These can also be defined in the last source file.
138
139    *Iq* and *Iqxy* also be instead be python functions defining the
140    kernel.  If they are marked as *Iq.vectorized = True* then the
141    kernel is passed the entire *q* vector at once, otherwise it is
142    passed values one *q* at a time.  The performance improvement of
143    this step is significant.
144
145    *demo* is a dictionary of parameter=value defining a set of
146    parameters to use by default when *compare* is called.  Any
147    parameter not set in *demo* gets the initial value from the
148    parameter list.  *demo* is mostly needed to set the default
149    polydispersity values for tests.
150
151    *oldname* is the name of the model in sasview before sasmodels
152    was split into its own package, and *oldpars* is a dictionary
153    of *parameter: old_parameter* pairs defining the new names for
154    the parameters.  This is used by *compare* to check the values
155    of the new model against the values of the old model before
156    you are ready to add the new model to sasmodels.
157
158
159An *info* dictionary is constructed from the kernel meta data and
160returned to the caller.
161
162The model evaluator, function call sequence consists of q inputs and the return vector,
163followed by the loop value/weight vector, followed by the values for
164the non-polydisperse parameters, followed by the lengths of the
165polydispersity loops.  To construct the call for 1D models, the
166categories *fixed-1d* and *pd-1d* list the names of the parameters
167of the non-polydisperse and the polydisperse parameters respectively.
168Similarly, *fixed-2d* and *pd-2d* provide parameter names for 2D models.
169The *pd-rel* category is a set of those parameters which give
170polydispersitiy as a portion of the value (so a 10% length dispersity
171would use a polydispersity value of 0.1) rather than absolute
172dispersity such as an angle plus or minus 15 degrees.
173
174The *volume* category lists the volume parameters in order for calls
175to volume within the kernel (used for volume normalization) and for
176calls to ER and VR for effective radius and volume ratio respectively.
177
178The *orientation* and *magnetic* categories list the orientation and
179magnetic parameters.  These are used by the sasview interface.  The
180blank category is for parameters such as scale which don't have any
181other marking.
182
183The doc string at the start of the kernel module will be used to
184construct the model documentation web pages.  Embedded figures should
185appear in the subdirectory "img" beside the model definition, and tagged
186with the kernel module name to avoid collision with other models.  Some
187file systems are case-sensitive, so only use lower case characters for
188file names and extensions.
189
190
191The function :func:`make` loads the metadata from the module and returns
192the kernel source.  The function :func:`doc` extracts the doc string
193and adds the parameter table to the top.  The function :func:`model_sources`
194returns a list of files required by the model.
195
196Code follows the C99 standard with the following extensions and conditions::
197
198    M_PI_180 = pi/180
199    M_4PI_3 = 4pi/3
200    square(x) = x*x
201    cube(x) = x*x*x
202    sinc(x) = sin(x)/x, with sin(0)/0 -> 1
203    all double precision constants must include the decimal point
204    all double declarations may be converted to half, float, or long double
205    FLOAT_SIZE is the number of bytes in the converted variables
206"""
207from __future__ import print_function
208
209# TODO: identify model files which have changed since loading and reload them.
210
211import sys
212from os.path import abspath, dirname, join as joinpath, exists, basename, \
213    splitext
214import re
215import string
216
217import numpy as np
218
219#__all__ = ["make", "doc", "model_sources", "convert_type"]
220
221C_KERNEL_TEMPLATE_PATH = joinpath(dirname(__file__), 'kernel_template.c')
222
223F16 = np.dtype('float16')
224F32 = np.dtype('float32')
225F64 = np.dtype('float64')
226try:  # CRUFT: older numpy does not support float128
227    F128 = np.dtype('float128')
228except TypeError:
229    F128 = None
230
231# Scale and background, which are parameters common to every form factor
232COMMON_PARAMETERS = [
233    ["scale", "", 1, [0, np.inf], "", "Source intensity"],
234    ["background", "1/cm", 0, [0, np.inf], "", "Source background"],
235    ]
236
237# Conversion from units defined in the parameter table for each model
238# to units displayed in the sphinx documentation.
239RST_UNITS = {
240    "Ang": "|Ang|",
241    "1/Ang": "|Ang^-1|",
242    "1/Ang^2": "|Ang^-2|",
243    "1e-6/Ang^2": "|1e-6Ang^-2|",
244    "degrees": "degree",
245    "1/cm": "|cm^-1|",
246    "Ang/cm": "|Ang*cm^-1|",
247    "g/cm3": "|g/cm^3|",
248    "mg/m2": "|mg/m^2|",
249    "": "None",
250    }
251
252# Headers for the parameters tables in th sphinx documentation
253PARTABLE_HEADERS = [
254    "Parameter",
255    "Description",
256    "Units",
257    "Default value",
258    ]
259
260# Minimum width for a default value (this is shorter than the column header
261# width, so will be ignored).
262PARTABLE_VALUE_WIDTH = 10
263
264# Documentation header for the module, giving the model name, its short
265# description and its parameter table.  The remainder of the doc comes
266# from the module docstring.
267DOC_HEADER = """.. _%(id)s:
268
269%(name)s
270=======================================================
271
272%(title)s
273
274%(parameters)s
275
276%(returns)s
277
278%(docs)s
279"""
280
281def format_units(units):
282    """
283    Convert units into ReStructured Text format.
284    """
285    return "string" if isinstance(units, list) else RST_UNITS.get(units, units)
286
287def make_partable(pars):
288    """
289    Generate the parameter table to include in the sphinx documentation.
290    """
291    column_widths = [
292        max(len(p[0]) for p in pars),
293        max(len(p[-1]) for p in pars),
294        max(len(format_units(p[1])) for p in pars),
295        PARTABLE_VALUE_WIDTH,
296        ]
297    column_widths = [max(w, len(h))
298                     for w, h in zip(column_widths, PARTABLE_HEADERS)]
299
300    sep = " ".join("="*w for w in column_widths)
301    lines = [
302        sep,
303        " ".join("%-*s" % (w, h)
304                 for w, h in zip(column_widths, PARTABLE_HEADERS)),
305        sep,
306        ]
307    for p in pars:
308        lines.append(" ".join([
309            "%-*s" % (column_widths[0], p[0]),
310            "%-*s" % (column_widths[1], p[-1]),
311            "%-*s" % (column_widths[2], format_units(p[1])),
312            "%*g" % (column_widths[3], p[2]),
313            ]))
314    lines.append(sep)
315    return "\n".join(lines)
316
317def _search(search_path, filename):
318    """
319    Find *filename* in *search_path*.
320
321    Raises ValueError if file does not exist.
322    """
323    for path in search_path:
324        target = joinpath(path, filename)
325        if exists(target):
326            return target
327    raise ValueError("%r not found in %s" % (filename, search_path))
328
329def model_sources(info):
330    """
331    Return a list of the sources file paths for the module.
332    """
333    search_path = [dirname(info['filename']),
334                   abspath(joinpath(dirname(__file__), 'models'))]
335    return [_search(search_path, f) for f in info['source']]
336
337# Pragmas for enable OpenCL features.  Be sure to protect them so that they
338# still compile even if OpenCL is not present.
339_F16_PRAGMA = """\
340#if defined(__OPENCL_VERSION__) && !defined(cl_khr_fp16)
341#  pragma OPENCL EXTENSION cl_khr_fp16: enable
342#endif
343"""
344
345_F64_PRAGMA = """\
346#if defined(__OPENCL_VERSION__) && !defined(cl_khr_fp64)
347#  pragma OPENCL EXTENSION cl_khr_fp64: enable
348#endif
349"""
350
351def convert_type(source, dtype):
352    """
353    Convert code from double precision to the desired type.
354
355    Floating point constants are tagged with 'f' for single precision or 'L'
356    for long double precision.
357    """
358    if dtype == F16:
359        fbytes = 2
360        source = _F16_PRAGMA + _convert_type(source, "half", "f")
361    elif dtype == F32:
362        fbytes = 4
363        source = _convert_type(source, "float", "f")
364    elif dtype == F64:
365        fbytes = 8
366        source = _F64_PRAGMA + source  # Source is already double
367    elif dtype == F128:
368        fbytes = 16
369        source = _convert_type(source, "long double", "L")
370    else:
371        raise ValueError("Unexpected dtype in source conversion: %s"%dtype)
372    return ("#define FLOAT_SIZE %d\n"%fbytes)+source
373
374
375def _convert_type(source, type_name, constant_flag):
376    """
377    Replace 'double' with *type_name* in *source*, tagging floating point
378    constants with *constant_flag*.
379    """
380    # Convert double keyword to float/long double/half.
381    # Accept an 'n' # parameter for vector # values, where n is 2, 4, 8 or 16.
382    # Assume complex numbers are represented as cdouble which is typedef'd
383    # to double2.
384    source = re.sub(r'(^|[^a-zA-Z0-9_]c?)double(([248]|16)?($|[^a-zA-Z0-9_]))',
385                    r'\1%s\2'%type_name, source)
386    # Convert floating point constants to single by adding 'f' to the end,
387    # or long double with an 'L' suffix.  OS/X complains if you don't do this.
388    source = re.sub(r'[^a-zA-Z_](\d*[.]\d+|\d+[.]\d*)([eE][+-]?\d+)?',
389                    r'\g<0>%s'%constant_flag, source)
390    return source
391
392
393def kernel_name(info, is_2d):
394    """
395    Name of the exported kernel symbol.
396    """
397    return info['name'] + "_" + ("Iqxy" if is_2d else "Iq")
398
399
400def categorize_parameters(pars):
401    """
402    Build parameter categories out of the the parameter definitions.
403
404    Returns a dictionary of categories.
405    """
406    partype = {
407        'volume': [], 'orientation': [], 'magnetic': [], '': [],
408        'fixed-1d': [], 'fixed-2d': [], 'pd-1d': [], 'pd-2d': [],
409        'pd-rel': set(),
410    }
411
412    for p in pars:
413        name, ptype = p[0], p[4]
414        if ptype == 'volume':
415            partype['pd-1d'].append(name)
416            partype['pd-2d'].append(name)
417            partype['pd-rel'].add(name)
418        elif ptype == 'magnetic':
419            partype['fixed-2d'].append(name)
420        elif ptype == 'orientation':
421            partype['pd-2d'].append(name)
422        elif ptype == '':
423            partype['fixed-1d'].append(name)
424            partype['fixed-2d'].append(name)
425        else:
426            raise ValueError("unknown parameter type %r" % ptype)
427        partype[ptype].append(name)
428
429    return partype
430
431def indent(s, depth):
432    """
433    Indent a string of text with *depth* additional spaces on each line.
434    """
435    spaces = " "*depth
436    sep = "\n" + spaces
437    return spaces + sep.join(s.split("\n"))
438
439
440LOOP_OPEN = """\
441for (int %(name)s_i=0; %(name)s_i < N%(name)s; %(name)s_i++) {
442  const double %(name)s = loops[2*(%(name)s_i%(offset)s)];
443  const double %(name)s_w = loops[2*(%(name)s_i%(offset)s)+1];\
444"""
445def build_polydispersity_loops(pd_pars):
446    """
447    Build polydispersity loops
448
449    Returns loop opening and loop closing
450    """
451    depth = 4
452    offset = ""
453    loop_head = []
454    loop_end = []
455    for name in pd_pars:
456        subst = {'name': name, 'offset': offset}
457        loop_head.append(indent(LOOP_OPEN % subst, depth))
458        loop_end.insert(0, (" "*depth) + "}")
459        offset += '+N' + name
460        depth += 2
461    return "\n".join(loop_head), "\n".join(loop_end)
462
463C_KERNEL_TEMPLATE = None
464def make_model(info):
465    """
466    Generate the code for the kernel defined by info, using source files
467    found in the given search path.
468    """
469    # TODO: need something other than volume to indicate dispersion parameters
470    # No volume normalization despite having a volume parameter.
471    # Thickness is labelled a volume in order to trigger polydispersity.
472    # May want a separate dispersion flag, or perhaps a separate category for
473    # disperse, but not volume.  Volume parameters also use relative values
474    # for the distribution rather than the absolute values used by angular
475    # dispersion.  Need to be careful that necessary parameters are available
476    # for computing volume even if we allow non-disperse volume parameters.
477
478    # Load template
479    global C_KERNEL_TEMPLATE
480    if C_KERNEL_TEMPLATE is None:
481        with open(C_KERNEL_TEMPLATE_PATH) as fid:
482            C_KERNEL_TEMPLATE = fid.read()
483
484    # Load additional sources
485    source = [open(f).read() for f in model_sources(info)]
486
487    # Prepare defines
488    defines = []
489    partype = info['partype']
490    pd_1d = partype['pd-1d']
491    pd_2d = partype['pd-2d']
492    fixed_1d = partype['fixed-1d']
493    fixed_2d = partype['fixed-1d']
494
495    iq_parameters = [p[0]
496                     for p in info['parameters'][2:] # skip scale, background
497                     if p[0] in set(fixed_1d + pd_1d)]
498    iqxy_parameters = [p[0]
499                       for p in info['parameters'][2:] # skip scale, background
500                       if p[0] in set(fixed_2d + pd_2d)]
501    volume_parameters = [p[0]
502                         for p in info['parameters']
503                         if p[4] == 'volume']
504
505    # Fill in defintions for volume parameters
506    if volume_parameters:
507        defines.append(('VOLUME_PARAMETERS',
508                        ','.join(volume_parameters)))
509        defines.append(('VOLUME_WEIGHT_PRODUCT',
510                        '*'.join(p + '_w' for p in volume_parameters)))
511
512    # Generate form_volume function from body only
513    if info['form_volume'] is not None:
514        if volume_parameters:
515            vol_par_decl = ', '.join('double ' + p for p in volume_parameters)
516        else:
517            vol_par_decl = 'void'
518        defines.append(('VOLUME_PARAMETER_DECLARATIONS',
519                        vol_par_decl))
520        fn = """\
521double form_volume(VOLUME_PARAMETER_DECLARATIONS);
522double form_volume(VOLUME_PARAMETER_DECLARATIONS) {
523    %(body)s
524}
525""" % {'body':info['form_volume']}
526        source.append(fn)
527
528    # Fill in definitions for Iq parameters
529    defines.append(('IQ_KERNEL_NAME', info['name'] + '_Iq'))
530    defines.append(('IQ_PARAMETERS', ', '.join(iq_parameters)))
531    if fixed_1d:
532        defines.append(('IQ_FIXED_PARAMETER_DECLARATIONS',
533                        ', \\\n    '.join('const double %s' % p for p in fixed_1d)))
534    if pd_1d:
535        defines.append(('IQ_WEIGHT_PRODUCT',
536                        '*'.join(p + '_w' for p in pd_1d)))
537        defines.append(('IQ_DISPERSION_LENGTH_DECLARATIONS',
538                        ', \\\n    '.join('const int N%s' % p for p in pd_1d)))
539        defines.append(('IQ_DISPERSION_LENGTH_SUM',
540                        '+'.join('N' + p for p in pd_1d)))
541        open_loops, close_loops = build_polydispersity_loops(pd_1d)
542        defines.append(('IQ_OPEN_LOOPS',
543                        open_loops.replace('\n', ' \\\n')))
544        defines.append(('IQ_CLOSE_LOOPS',
545                        close_loops.replace('\n', ' \\\n')))
546    if info['Iq'] is not None:
547        defines.append(('IQ_PARAMETER_DECLARATIONS',
548                        ', '.join('double ' + p for p in iq_parameters)))
549        fn = """\
550double Iq(double q, IQ_PARAMETER_DECLARATIONS);
551double Iq(double q, IQ_PARAMETER_DECLARATIONS) {
552    %(body)s
553}
554""" % {'body':info['Iq']}
555        source.append(fn)
556
557    # Fill in definitions for Iqxy parameters
558    defines.append(('IQXY_KERNEL_NAME', info['name'] + '_Iqxy'))
559    defines.append(('IQXY_PARAMETERS', ', '.join(iqxy_parameters)))
560    if fixed_2d:
561        defines.append(('IQXY_FIXED_PARAMETER_DECLARATIONS',
562                        ', \\\n    '.join('const double %s' % p for p in fixed_2d)))
563    if pd_2d:
564        defines.append(('IQXY_WEIGHT_PRODUCT',
565                        '*'.join(p + '_w' for p in pd_2d)))
566        defines.append(('IQXY_DISPERSION_LENGTH_DECLARATIONS',
567                        ', \\\n    '.join('const int N%s' % p for p in pd_2d)))
568        defines.append(('IQXY_DISPERSION_LENGTH_SUM',
569                        '+'.join('N' + p for p in pd_2d)))
570        open_loops, close_loops = build_polydispersity_loops(pd_2d)
571        defines.append(('IQXY_OPEN_LOOPS',
572                        open_loops.replace('\n', ' \\\n')))
573        defines.append(('IQXY_CLOSE_LOOPS',
574                        close_loops.replace('\n', ' \\\n')))
575    if info['Iqxy'] is not None:
576        defines.append(('IQXY_PARAMETER_DECLARATIONS',
577                        ', '.join('double ' + p for p in iqxy_parameters)))
578        fn = """\
579double Iqxy(double qx, double qy, IQXY_PARAMETER_DECLARATIONS);
580double Iqxy(double qx, double qy, IQXY_PARAMETER_DECLARATIONS) {
581    %(body)s
582}
583""" % {'body':info['Iqxy']}
584        source.append(fn)
585
586    # Need to know if we have a theta parameter for Iqxy; it is not there
587    # for the magnetic sphere model, for example, which has a magnetic
588    # orientation but no shape orientation.
589    if 'theta' in pd_2d:
590        defines.append(('IQXY_HAS_THETA', '1'))
591
592    #for d in defines: print(d)
593    defines = '\n'.join('#define %s %s' % (k, v) for k, v in defines)
594    sources = '\n\n'.join(source)
595    return C_KERNEL_TEMPLATE % {
596        'DEFINES': defines,
597        'SOURCES': sources,
598        }
599
600def make_info(kernel_module):
601    """
602    Interpret the model definition file, categorizing the parameters.
603    """
604    #print(kernelfile)
605    category = getattr(kernel_module, 'category', None)
606    parameters = COMMON_PARAMETERS + kernel_module.parameters
607    # Default the demo parameters to the starting values for the individual
608    # parameters if an explicit demo parameter set has not been specified.
609    demo_parameters = getattr(kernel_module, 'demo', None)
610    if demo_parameters is None:
611        demo_parameters = dict((p[0], p[2]) for p in parameters)
612    filename = abspath(kernel_module.__file__)
613    kernel_id = splitext(basename(filename))[0]
614    name = getattr(kernel_module, 'name', None)
615    if name is None:
616        name = " ".join(w.capitalize() for w in kernel_id.split('_'))
617    info = dict(
618        id=kernel_id,  # string used to load the kernel
619        filename=abspath(kernel_module.__file__),
620        name=name,
621        title=kernel_module.title,
622        description=kernel_module.description,
623        category=category,
624        parameters=parameters,
625        demo=demo_parameters,
626        source=getattr(kernel_module, 'source', []),
627        oldname=kernel_module.oldname,
628        oldpars=kernel_module.oldpars,
629        )
630    # Fill in attributes which default to None
631    info.update((k, getattr(kernel_module, k, None))
632                for k in ('ER', 'VR', 'form_volume', 'Iq', 'Iqxy'))
633    # Fill in the derived attributes
634    info['limits'] = dict((p[0], p[3]) for p in info['parameters'])
635    info['partype'] = categorize_parameters(info['parameters'])
636    info['defaults'] = dict((p[0], p[2]) for p in info['parameters'])
637    return info
638
639def make(kernel_module):
640    """
641    Build an OpenCL/ctypes function from the definition in *kernel_module*.
642
643    The module can be loaded with a normal python import statement if you
644    know which module you need, or with __import__('sasmodels.model.'+name)
645    if the name is in a string.
646    """
647    info = make_info(kernel_module)
648    # Assume if one part of the kernel is python then all parts are.
649    source = make_model(info) if not callable(info['Iq']) else None
650    return source, info
651
652section_marker = re.compile(r'\A(?P<first>[%s])(?P=first)*\Z'
653                            %re.escape(string.punctuation))
654def _convert_section_titles_to_boldface(lines):
655    """
656    Do the actual work of identifying and converting section headings.
657    """
658    prior = None
659    for line in lines:
660        if prior is None:
661            prior = line
662        elif section_marker.match(line):
663            if len(line) >= len(prior):
664                yield "".join(("**", prior, "**"))
665                prior = None
666            else:
667                yield prior
668                prior = line
669        else:
670            yield prior
671            prior = line
672    if prior is not None:
673        yield prior
674
675def convert_section_titles_to_boldface(s):
676    """
677    Use explicit bold-face rather than section headings so that the table of
678    contents is not polluted with section names from the model documentation.
679
680    Sections are identified as the title line followed by a line of punctuation
681    at least as long as the title line.
682    """
683    return "\n".join(_convert_section_titles_to_boldface(s.split('\n')))
684
685def doc(kernel_module):
686    """
687    Return the documentation for the model.
688    """
689    Iq_units = "The returned value is scaled to units of |cm^-1| |sr^-1|, absolute scale."
690    Sq_units = "The returned value is a dimensionless structure factor, $S(q)$."
691    info = make_info(kernel_module)
692    is_Sq = ("structure-factor" in info['category'])
693    #docs = kernel_module.__doc__
694    docs = convert_section_titles_to_boldface(kernel_module.__doc__)
695    subst = dict(id=info['id'].replace('_', '-'),
696                 name=info['name'],
697                 title=info['title'],
698                 parameters=make_partable(info['parameters']),
699                 returns=Sq_units if is_Sq else Iq_units,
700                 docs=docs)
701    return DOC_HEADER % subst
702
703
704
705def demo_time():
706    """
707    Show how long it takes to process a model.
708    """
709    from .models import cylinder
710    import datetime
711    tic = datetime.datetime.now()
712    make(cylinder)
713    toc = (datetime.datetime.now() - tic).total_seconds()
714    print("time: %g"%toc)
715
716def main():
717    """
718    Program which prints the source produced by the model.
719    """
720    if len(sys.argv) <= 1:
721        print("usage: python -m sasmodels.generate modelname")
722    else:
723        name = sys.argv[1]
724        import sasmodels.models
725        __import__('sasmodels.models.' + name)
726        model = getattr(sasmodels.models, name)
727        source, _ = make(model)
728        print(source)
729
730if __name__ == "__main__":
731    main()
Note: See TracBrowser for help on using the repository browser.