autogenerated plot in doc for rpa is not helpful

[butler]

The autogeneration of an example plot in sasmodel documentation based on default parameters is quite useful normally, it can be problematic for multiplicity models where all the parameters of the multiplicity have the same value. In particular the rpa has scattering length of each component as a multiplicity parameter so all are set equal to the one default. Unfortunately that means that I(Q)=0 at all Q. It would be nice if we could get a sensible plot in such, admittedly rare, cases.

[pkienzle]

(1) Accept vector values for parameter defaults so you can provide an interesting default parameter set.

parameters = [
    ["case_num", "", 1, [CASES], "", "Component organization"],

    ["N[4]", "", [1000.0, 1000.0, 500., 750.], [1, inf], "", "Degree of polymerization"],
    ...
    ["K34", "", -0.0004, [-inf, inf], "", "C:D interaction parameter"],
]

The doc generator will need to know how to format parameter lists.

(2) Use the "demo" parameter set for the doc plot. We can remove demo parameters for all models that have reasonable defaults, which is to say most of them. Demo already supports vector parameters:

demo = {
    "N": [1000., 1000., 500., 750.],
    ...
}

The doc generator will need to include a nicely formatted list of parameter values that are not the default value as part of the figure caption.

(3) Give the user direct control over the sphinx layout of the parameter table. This would allow us to define the table using sasview 3.x parameter names while still having a compact table representation:

parameters = [
    ["case_num", "", 1, [CASES], "", "Component organization"],

    ["Na", "", 1000.0, [1, inf], "", "Degree of polymerization"],
    ["Nb", "", 1000.0, [1, inf], "", "Degree of polymerization"],
    ...
    ["Kcd", "", -0.0004, [-inf, inf], "", "C:D interaction parameter"],
]
parameter_table = """
============== ========================= ======= =============
Parameter      Description               Units   Default value
============== ========================= ======= =============
scale          Source intensity          None                1
background     Source background         |cm^-1|         0.001
case_num       Component organization    None                1
Na,...,Nd      Degree of polymerization  None             1000
Phia,...,Phid  Volume fraction           None             0.25
va,...,vd      specific volume           mL/mol            100
La,...,Ld      scattering length         fm                 10
ba,...,bd      segment length            |Ang|               5
Kab,...,Kcd    Component interaction     None          -0.0004
============== ========================= ======= =============
"""

(4) Allow the parameter table to be manipulated after construction. We should probably do this anyway since it is pretty trivial and provides a lot of flexibility. The result would look something like:

from sasmodels import modelinfo

parameters = [
    ["case_num", "", 1, [CASES], "", "Component organization"],

    ["N[4]", "", 1000.0, [1, inf], "", "Degree of polymerization"],
    ...
    ["K34", "", -0.0004, [-inf, inf], "", "C:D interaction parameter"],
]
parameters = modelinfo.make_parameter_table(parameters)
demo = {
    "N": [1000., 1000., 500., 750.],
    ...
}
for k, v in modelinfo.expand_pars(parameters, demo):
    for p in parameters.user_parameters:
        if p.id == k: 
            p.default = v

We could then rename the user parameters from N1,N2,… to Na, Nb,… using:

for p in parameters.user_parameters:
    p.id = p.id.replace('1','a').replace('2','b').replace('3','c').replace('4','d')

This approach will be somewhat brittle. Any changes to the internal data structures will require all affected models to be updated. The doc generator won't know how to handle an arbitrary manipulation of the internal data structures, so this would need to be in combination with option (3).

---

These options are not exclusive. That is, we may want to have independent control of the default values on vectors while using the demo values to generate the default plot while allowing the user to override the parameter table while allowing direct manipulation of the underlying ParameterTable data structure.

[smk78]

Also see attachments in #1261