Add notes to doc about fitting integer parameters (Trac #882)

[pkienzle]

The following notes were in the multilayer vesicle model in IGOR:

The value returned by the fitting routine for the number of water/shell pairs will be a floating point number. The physical reality must be an integer number of layers. In the model function, the value is truncated so that only the integer portion is used. That is 5.95 "pairs" is actually calculating the scattering for 5 pairs. ''[sasmodels rounds to 6 rather than truncates to 5]''

and:

This is a highly non-linear model function, complicated by the fact that the number of water/shell pairs must physically be an integer value, although the optimization treats it as a floating point value. For the best possible experience:

• Start with the best possible guess
• Using a priori knowledge, hold as many parameters fixed as possible
• if N=1, tw (water thickness) must by definition be zero. Both N and tw must be fixed during fitting.
• If N>1, use constraints to keep N > 1 (set this up in the curve fitting dialog)
• To force N to "move" during fitting, you may need to set an "epsilon" wave to force a larger step in that direction. epsilon = 0.001 is good for all parameters other than N, which should be set to 1. (set this up in the curve fitting dialog) ''[epsilon is an IGOR control on individual fit parameters; in bumps, don't use L-M or other derivative-based optimizers]''

Some of these details should be added to the multilayer vesicle docs, but others are more general and will apply to any system with integer parameters. See ticket http://trac.sasview.org/ticket/843 and the pull request [https://github.com/SasView/sasmodels/pull/27 27] for context.

Also mentioned:

The resolution smeared version gives the most appropriate view of the model. Note that the resolution smearing calculation uses 76 Gauss quadrature points to properly smear the model since the function is HIGHLY oscillatory, especially around the q-values that correspond to the repeat distance of the layers. This can make the calculations rather slow.

Better control of resolution is ticketed in SasView/sasmodels#263 and #839. Adaptive integration is recommended in SasView/sasmodels#535. Hints for when the user should turn on oversampling in q for the resolution calculation should be documented (i.e., when the function is oscillatory or the data are sparse). Note that polydispersity reduces oscillation, which means the resolution calculation is cheaper.

Migrated from http://trac.sasview.org/ticket/882

{
    "status": "closed",
    "changetime": "2019-03-28T16:11:53",
    "_ts": "2019-03-28 16:11:53.092724+00:00",
    "description": "The following notes were in the multilayer vesicle model in IGOR:\n\n\n The value returned by the fitting routine for the number of water/shell pairs will be a floating point number. The physical reality must be an integer number of layers. In the model function, the value is truncated so that only the integer portion is used. That is 5.95 \"pairs\" is actually calculating the scattering for 5 pairs. ''[sasmodels rounds to 6 rather than truncates to 5]''\n\nand:\n\n This is a highly non-linear model function, complicated by the fact that the number of water/shell pairs must physically be an integer value, although the optimization treats it as a floating point value. For the best possible experience:\n - Start with the best possible guess\n - Using a priori knowledge, hold as many parameters fixed as possible\n - if N=1, tw (water thickness) must by definition be zero. Both N and tw must be fixed during fitting.\n - If N>1, use constraints to keep N > 1 (set this up in the curve fitting dialog)\n - To force N to \"move\" during fitting, you may need to set an \"epsilon\" wave to force a larger step in that direction. epsilon = 0.001 is good for all parameters other than N, which should be set to 1. (set this up in the curve fitting dialog) ''[epsilon is an IGOR control on individual fit parameters; in bumps, don't use L-M or other derivative-based optimizers]''\n\nSome of these details should be added to the multilayer vesicle docs, but others are more general and will apply to any system with integer parameters. See ticket SasView/sasview#843 and the pull request [https://github.com/SasView/sasmodels/pull/27 27] for context.\n\nAlso mentioned:\n\n The resolution smeared version gives the most appropriate view of the model. Note that the resolution smearing calculation uses 76 Gauss quadrature points to properly smear the model since the function is HIGHLY oscillatory, especially around the q-values that correspond to the repeat distance of the layers. This can make the calculations rather slow.\n\nBetter control of resolution is ticketed in SasView/sasview#715 and SasView/sasview#717.  Adaptive integration is recommended in SasView/sasview#392.  Hints for when the user should turn on oversampling in q for the resolution calculation should be documented (i.e., when the function is oscillatory or the data are sparse). Note that polydispersity reduces oscillation, which means the resolution calculation is cheaper.\n",
    "reporter": "pkienzle",
    "cc": "",
    "resolution": "fixed",
    "workpackage": "SasView Documentation",
    "time": "2017-03-10T13:38:06",
    "component": "SasView",
    "summary": "Add notes to doc about fitting integer parameters",
    "priority": "major",
    "keywords": "",
    "milestone": "SasView 4.3.0",
    "owner": "smk78",
    "type": "enhancement"
}

[pkienzle]

Trac update at 2017/03/13 15:24:03: pkienzle commented:

Multilayer vesicle docs now include the above details. The main docs for the fitting perspective should still be updated, as well as the docs for other models with fittable integer parameters (e.g., pearl necklace).

[smk78]

Trac update at 2017/03/14 15:50:51: smk78 changed workpackage from "SasView Bug Fixing" to "SasView Documentation"

[butlerpd]

Trac update at 2017/10/27 16:24:00: butler changed milestone from "SasView 4.2.0" to "SasView 4.3.0"

[pkienzle]

Trac update at 2018/11/15 15:40:23: pkienzle commented:

See also SasView/sasmodels#256.

[smk78]

Trac update at 2019/03/28 16:11:53:

• smk78 commented:

In changeset b7ce5ad:

#!CommitTicketReference repository="sasview" revision="b7ce5ad13cff1bb692e5cac14d5eeb68461dd835"
Added section on Fitting Integer Parameters. Closes SasView/sasview#968

• smk78 changed owner from "" to "smk78"
• smk78 changed resolution from "" to "fixed"
• smk78 changed status from "new" to "closed"