Changeset d7c29ce in sasview for src/sas

Timestamp:

Nov 1, 2016 3:29:47 AM (8 years ago)

Author:

wojciech

Branches:

master, ESS_GUI, ESS_GUI_Docs, ESS_GUI_batch_fitting, ESS_GUI_bumps_abstraction, ESS_GUI_iss1116, ESS_GUI_iss879, ESS_GUI_iss959, ESS_GUI_opencl, ESS_GUI_ordering, ESS_GUI_sync_sascalc, costrafo411, magnetic_scatt, release-4.1.1, release-4.1.2, release-4.2.2, ticket-1009, ticket-1094-headless, ticket-1242-2d-resolution, ticket-1243, ticket-1249, ticket885, unittest-saveload

Children:

20f07dbc

Parents:

907b24b (diff), 20cfa23 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merged with master

Location:

src/sas/sasgui/perspectives/fitting

Files:

• media/plugin.rst (modified) (7 diffs)
• basepage.py (modified) (2 diffs)

src/sas/sasgui/perspectives/fitting/media/plugin.rst

@@ -11 +11 @@
 There are essentially three ways to generate new fitting models for SasView:
 
-* Using the SasView :ref:`New_Plugin_Model` helper dialog (best for beginners and/or relatively simple models)
-* By copying/editing an existing model (this can include models generated by the *New Plugin Model* dialog) in the :ref:`Python_shell` or :ref:`Advanced_Plugin_Editor` as described below (suitable for all use cases)
-* By writing a model from scratch outside of SasView (only recommended for code monkeys!)
+* Using the SasView :ref:`New_Plugin_Model` helper dialog (best for beginners
+  and/or relatively simple models)
+* By copying/editing an existing model (this can include models generated by
+  the *New Plugin Model* dialog) in the :ref:`Python_shell` or
+  :ref:`Advanced_Plugin_Editor` as described below (suitable for all use cases)
+* By writing a model from scratch outside of SasView (only recommended for
+  code monkeys!)
 
 Overview
@@ -23 +27 @@
 
 the next time SasView is started it will compile the plugin and add
-it to the list of *Plugin Models* in a FitPage.
+it to the list of *Customized Models* in a FitPage.
 
 SasView models can be of three types:
@@ -57 +61 @@
 - If necessary use underscore to separate words (i.e. barbell not BarBell or
   broad_peak not BroadPeak)
-- Do not include “modelâ€ￜ in the name (i.e. barbell not BarBellModel)
+- Do not include "model" in the name (i.e. barbell not BarBellModel)
 
 
@@ -479 +483 @@
     }
 
-The C model operates on a single $q$ value at a time.  The code will be
-run in parallel across different $q$ values, either on the graphics card
-or the processor.
-
-Rather than returning NAN from Iq, you must define the *INVALID(v)*.  The
-*v* parameter lets you access all the parameters in the model using
-*v.par1*, *v.par2*, etc. For example::
-
-    #define INVALID(v) (v.bell_radius < v.radius)
-
 *Iqxy* is similar to *Iq*, except it uses parameters *qx, qy* instead of *q*,
-and it includes orientation parameters. As in python models, *form_volume*
-includes only the volume parameters.  *Iqxy* will default to
-*Iq(sqrt(qx**2 + qy**2), par1, ...)* and *form_volume* will default to 1.0.
-
-The C code follows the C99 standard, including the usual math functions,
-as defined in
-`OpenCL <https://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/mathFunctions.html>`_.
-
-The standard constants and functions include the following::
-
-    M_PI = pi
-    M_PI_2 = pi/2
-    M_PI_4 = pi/4
-    M_E = e
-    M_SQRT1_2 = 1/sqrt(2)
-    NAN = NaN
-    INFINITY = 1/0
-    erf(x) = error function
-    erfc(x) = 1-erf(x)
-    expm1(x) = exp(x) - 1
-    tgamma(x) = gamma function
-
-Some non-standard constants and functions are also provided::
-
-    M_PI_180 = pi/180
-    M_4PI_3 = 4pi/3
-    square(x) = x*x
-    cube(x) = x*x*x
-    sinc(x) = sin(x)/x, with sin(0)/0 -> 1
-    SINCOS(x, s, c) sets s=sin(angle) and c=cos(angle)
-    powr(x, y) = x^y for x >= 0
-    pown(x, n) = x^n for n integer
-
-**source=['lib/fn.c', ...]** includes the listed C source files in the
+and it includes orientation parameters.
+
+*form_volume* defines the volume of the shape. As in python models, it 
+includes only the volume parameters.
+
+*Iqxy* will default to *Iq(sqrt(qx**2 + qy**2), par1, ...)* and
+*form_volume* will default to 1.0.
+
+**source=['fn.c', ...]** includes the listed C source files in the
 program before *Iq* and *Iqxy* are defined. This allows you to extend the
-library of available C functions. Additional special functions and
-scattering calculations are defined in
-`sasmodels/models/lib <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib>`_,
-including::
-
-    sph_j1c(x) = 3 j1(x)/x = 3 (sin(x) - x cos(x))/x^3  [spherical bessel function]
-    sas_J1c(x) = 2 J1(x)/x  [bessel function of the first kind]
-    sas_gamma(x) = gamma function  [tgamma is unstable below 1]
-    sas_erf(x) = error function [erf is broken on some Intel OpenCL drivers]
-    sas_erfc(x) = 1-erf(x)
-    sas_J0(x) = J0(x)
-    sas_J1(x) = J1(x)
-    sas_JN(x) = JN(x)
-    Si(x) = integral sin(z)/z from 0 to x
-    Gauss76Wt = gaussian quadrature weights for 76 point integral
-    Gauss76Z = gaussian quadrature values for 76 point integral
-
-These functions have been tuned to be fast and numerically stable down
-to $q=0$ even in single precision.  In some cases they work around bugs
-which appear on some platforms but not others. So use them where needed!!!
+library of C functions available to your model.
 
 Models are defined using double precision declarations for the
-parameters and return values.  Declarations and constants will be converted
-to float or long double depending on the precision requested.
+parameters and return values.  When a model is run using single
+precision or long double precision, each variable is converted
+to the target type, depending on the precision requested.
 
 **Floating point constants must include the decimal point.**  This allows us
@@ -558 +509 @@
 use the builtin constant M_PI rather than 4*atan(1); it is faster and smaller!
 
-FLOAT_SIZE is the number of bytes in the converted variables. If your
-algorithm depends on precision (which is not uncommon for numerical
-algorithms), use the following::
-
-    #if FLOAT_SIZE>4
-    ... code for double precision ...
-    #else
-    ... code for single precision ...
-    #endif
-
-A value defined as SAS_DOUBLE will stay double precision; this should
-not be used since some graphics cards do not support double precision.
-
+The C model operates on a single $q$ value at a time.  The code will be
+run in parallel across different $q$ values, either on the graphics card
+or the processor.
+
+Rather than returning NAN from Iq, you must define the *INVALID(v)*.  The
+*v* parameter lets you access all the parameters in the model using
+*v.par1*, *v.par2*, etc. For example::
+
+    #define INVALID(v) (v.bell_radius < v.radius)
+
+Special Functions
+.................
+
+The C code follows the C99 standard, with the usual math functions,
+as defined in
+`OpenCL <https://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/mathFunctions.html>`_.
+This includes the following:
+
+    M_PI, M_PI_2, M_PI_4, M_SQRT1_2, M_E:
+        $\pi$, $\pi/2$, $\pi/4$, $1/\sqrt{2}$ and Euler's constant $e$
+    exp, log, pow(x,y), expm1, sqrt:
+        Power functions $e^x$, $\ln x$, $x^y$, $e^x - 1$, $\sqrt{x}$.
+        The function expm1(x) is accurate across all $x$, including $x$
+        very close to zero.
+    sin, cos, tan, asin, acos, atan:
+        Trigonometry functions and inverses, operating on radians.
+    sinh, cos, tanh, asinh, acosh, atanh:
+        Hyperbolic trigonometry functions.
+    atan2(y,x):
+        Angle from the $x$\ -axis to the point $(x,y)$, which is equal to
+        $\tan^{-1}(y/x)$ corrected for quadrant.  That is, if $x$ and $y$ are
+        both negative, then atan2(y,x) returns a value in quadrant III where
+        atan(y/x) would return a value in quadrant I. Similarly for
+        quadrants II and IV when $x$ and $y$ have opposite sign.
+    fmin(x,y), fmax(x,y), trunc, rint:
+        Floating point functions.  rint(x) returns the nearest integer.
+    NAN:
+        NaN, Not a Number, $0/0$.  Use isnan(x) to test for NaN.  Note that
+        you cannot use :code:`x == NAN` to test for NaN values since that
+        will always return false.  NAN does not equal NAN!
+    INFINITY:
+        $\infty, 1/0$.  Use isinf(x) to test for infinity, or isfinite(x)
+        to test for finite and not NaN.
+    erf, erfc, tgamma, lgamma:  **do not use**
+        Special functions that should be part of the standard, but are missing
+        or inaccurate on some platforms. Use sas_erf, sas_erfc and sas_gamma
+        instead (see below). Note: lgamma(x) has not yet been tested.
+
+Some non-standard constants and functions are also provided:
+
+    M_PI_180, M_4PI_3:
+        $\pi/{180}$, $\tfrac{4}{3}\pi$
+    SINCOS(x, s, c):
+        Macro which sets s=sin(x) and c=cos(x). The variables *c* and *s*
+        must be declared first.
+    square(x):
+        $x^2$
+    cube(x):
+        $x^3$
+    sinc(x):
+        $\sin(x)/x$, with limit $\sin(0)/0 = 1$.
+    powr(x, y):
+        $x^y$ for $x \ge 0$; this is faster than general $x^y$ on some GPUs.
+    pown(x, n):
+        $x^n$ for $n$ integer; this is faster than general $x^n$ on some GPUs.
+    FLOAT_SIZE:
+        The number of bytes in a floating point value.  Even though all
+        variables are declared double, they may be converted to single
+        precision float before running. If your algorithm depends on
+        precision (which is not uncommon for numerical algorithms), use
+        the following::
+
+            #if FLOAT_SIZE>4
+            ... code for double precision ...
+            #else
+            ... code for single precision ...
+            #endif
+    SAS_DOUBLE:
+        A replacement for :code:`double` so that the declared variable will
+        stay double precision; this should generally not be used since some
+        graphics cards do not support double precision.  There is no provision
+        for forcing a constant to stay double precision.
+
+The following special functions and scattering calculations are defined in
+`sasmodels/models/lib <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib>`_.
+These functions have been tuned to be fast and numerically stable down
+to $q=0$ even in single precision.  In some cases they work around bugs
+which appear on some platforms but not others. So use them where needed!!!
+
+    polevl(x, c, n):
+        Polynomial evaluation $p(x) = \sum_{i=0}^n c_i x^{n-i}$ using Horner's
+        method so it is faster and more accurate.
+
+        :code:`source = ["lib/polevl.c", ...]`
+
+    sas_gamma:
+        Gamma function $\text{sas_gamma}(x) = \Gamma(x)$.  The standard math
+        library gamma function, tgamma(x) is unstable below 1 on some platforms.
+
+        :code:`source = ["lib/sasgamma.c", ...]`
+
+    erf, erfc:
+        Error function
+        $\text{erf}(x) = \frac{1}{\sqrt\pi}\int_0^x e^{-t^2}\,dt$
+        and complementary error function
+        $\text{erfc}(x) = \frac{1}{\sqrt\pi}\int_x^\inf e^{-t^2}\,dt$.
+        The standard math library erf and erfc are slower and broken
+        on some platforms.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_erf.c", ...]`
+
+    sas_J0:
+        Bessel function of the first kind where
+        $J_0(x) = \frac{1}{\pi}\int_0^\pi \cos(x\sin(\tau))\,d\tau$.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J0.c", ...]`
+
+    sas_J1:
+        Bessel function of the first kind where
+        $J_1(x) = \frac{1}{\pi}\int_0^\pi \cos(\tau - x\sin(\tau))\,d\tau$.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J1.c", ...]`
+
+    sas_JN:
+        Bessel function of the first kind where
+        $J_n(x) = \frac{1}{\pi}\int_0^\pi \cos(n\tau - x\sin(\tau))\,d\tau$.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J0.c", "lib/sas_J1.c", "lib/sas_JN.c", ...]`
+
+    Si:
+        Sine integral $\text{Si}(x) = \int_0^x \tfrac{\sin t}{t}\,dt$.
+
+        :code:`soure = ["lib/Si.c", ...]`
+
+    sph_j1c(qr):
+        Spherical Bessel form
+        $F(qr) = 3 j_1(qr)/(qr) = 3 (\sin(qr) - qr \cos(qr))/{(qr)^3}$,
+        with a limiting value of 1 at $qr=0$.  This function uses a Taylor
+        series for small $qr$ for numerical accuracy.
+
+        :code:`source = ["lib/sph_j1c.c", ...]`
+
+    sas_J1c(qr):
+        Bessel form $F(qr) = 2 J_1(qr)/{(qr)}$, with a limiting value of 1 at $qr=0$.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J1.c", ...]`
+
+    Gauss76z[i], Gauss76Wt[i]:
+        Points $z_i$ and weights $w_i$ for 76-point Gaussian quadrature,
+        computing $\int_{-1}^1 f(z)\,dz \approx \sum_{i=1}^{76} w_i f(z_i)$.
+        Similar arrays are available in :code:`gauss20.c` for 20 point
+        quadrature and in :code:`gauss150.c` for 150 point quadrature.
+
+        :code:`source = ["gauss76.c", ...]`
+
+Problems with C models
+......................
+
+The graphics processor (GPU) in your computer is a specialized computer tuned
+for certain kinds of problems.  This leads to strange restrictions that you
+need to be aware of.  Your code may work fine on some platforms or for some
+models, but then return bad values on other platforms.  Some examples of
+particular problems:
+
+  **(1) Code is too complex, or uses too much memory.**  GPU devices only have a
+  limited amount of memory available for each processor.  If you run programs
+  which take too much memory, then rather than running multiple values in parallel
+  as it usually does, the GPU may only run a single version of the code at a
+  time, making it slower than running on the CPU.  It may fail to run on
+  some platforms, or worse, cause the screen to go blank or the system to reboot.
+
+  **(2) Code takes too long.**  Because GPU devices are used for the computer
+  display, the OpenCL drivers are very careful about the amount of time they
+  will allow any code to run.  For example, on OS X, the model will stop running
+  after 5 seconds regardless of whether the computation is complete.  You may end up
+  with only some of your 2D array defined, with the rest containing random
+  data. Or it may cause the screen to go blank or the system to reboot.
+
+  **(3) Memory is not aligned**.  The GPU hardware is specialized to operate on
+  multiple values simultaneously.  To keep the GPU simple the values in memory
+  must be aligned with the different GPU compute engines.  Not following these
+  rules can lead to unexpected values being loaded into memory, and wrong answers
+  computed.  The conclusion from a very long and strange debugging session was
+  that any arrays that you declare in your model should be a multiple of four.
+  For example::
+
+      double Iq(q, p1, p2, ...)
+      {
+          double vector[8];  // Only going to use seven slots, but declare 8
+          ...
+      }
+
+The first step when your model is behaving strangely is to set **single=False**.
+This automatically restricts the model to only run on the CPU, or on high-end
+GPU cards.  There can still be problems even on high-end cards, so you can force
+the model off the GPU by setting **opencl=False**.  This runs the model
+as a normal C program without any GPU restrictions so you know that
+strange results are probably from your code rather than the environment.  Once
+the code is debugged, you can compare your output to the output on the GPU.
+
+Although it can be difficult to get your model to work on the GPU, the reward
+can be a model that runs 1000x faster on a good card.  Even your laptop may
+show a 50x improvement or more over the equivalent pure python model.
 
 External C Models
@@ -577 +718 @@
 External C models are very much like embedded C models, except that
 *Iq*, *Iqxy* and *form_volume* are defined in an external source file
-loaded using the *source=[...]*  method. You need to supply the function
+loaded using the *source=[...]* statement. You need to supply the function
 declarations for each of these that you need instead of building them
 automatically from the parameter table.
@@ -804 +945 @@
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
 
-.. note::  This help document was last changed by Steve King, 10Oct2016
+.. note::  This help document was last changed by Steve King, 25Oct2016

src/sas/sasgui/perspectives/fitting/basepage.py

@@ -52 +52 @@
     FONT_VARIANT = 1
     ON_MAC = True
-
 
 class BasicPage(ScrolledPanel, PanelBase):
@@ -1457 +1456 @@
                 self.state_change = True
                 self._draw_model()
+                #Time delay introduced to prevent double compilation on Windows
+                #It seems to be threading related issue that triggers
+                #compilation twice at the same time
+                if ON_MAC == False:
+                    time.sleep(0.1)
                 self.Refresh()