Many models do not have their equation in the documentation (Trac #1240)

[butlerpd]

The Structure factors along with a number of other more complex models do not list the math used to compute them. Every model should have that which should of course match what the code is doing.

These omissions can at times be irritating when trying to answer a question about the model, often with the user sitting next to me and explaining how they just need to go to the documentation. Usually the documentation does refer to the underlying articles with equations but that can be a huge barrier.

One caveat may be that some models can be quite complex and the math itself may look daunting if not placed judiciously in the docs?

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

{
    "status": "closed",
    "changetime": "2019-03-27T11:03:40",
    "_ts": "2019-03-27 11:03:40.875273+00:00",
    "description": "The Structure factors along with a number of other more complex models do not list the math used to compute them.  Every model should have that which should of course match what the code is doing.\n\nThese omissions can at times be irritating when trying to answer a question about the model, often with the user sitting next to me and explaining how they just need to go to the documentation. Usually the documentation does refer to the underlying articles with equations but that can be a huge barrier.\n\nOne caveat may be that some models can be quite complex and the math itself may look daunting if not placed judiciously in the docs?",
    "reporter": "butler",
    "cc": "",
    "resolution": "wontfix",
    "workpackage": "SasView Documentation",
    "time": "2019-03-03T15:30:30",
    "component": "SasView",
    "summary": "Many models do not have their equation in the documentation",
    "priority": "critical",
    "keywords": "",
    "milestone": "SasView 4.3.0",
    "owner": "",
    "type": "defect"
}

[butlerpd]

Trac update at 2019/03/23 14:40:47: butler changed priority from "major" to "critical"

[smk78]

Trac update at 2019/03/26 14:01:33: smk78 commented:

The lack of equations for S(q) is noted in ticket http://trac.sasview.org/ticket/1187

P(q) models requiring attention are:

• flexible_cylinder
• flexible_cylinder_elliptical
• core_shell_ellipsoid (some reformatting needed)
• rpa

[smk78]

Trac update at 2019/03/26 17:13:52: smk78 commented:

After looking at the original reference and our codebase, I have concluded that it would be a tall order to accurately provide the equations for the flexible cylinder models in the model documentation. I have therefore highlighted this complexity in the docs and provided links to the source code for the interested reader to work it out for themselves if needs be.

[smk78]

Trac update at 2019/03/27 10:30:45: smk78 commented:

Corrected missing/poor rst/latex markup in the core_shell_ellipsoid docs.

[smk78]

Trac update at 2019/03/27 11:02:19: smk78 commented:

Similar to http://trac.sasview.org/ticket/1240#comment:3 above, the sheer complexity of the rpa model makes it too daunting to provide the equations in the model documentation. I have made some minor tweaks to the docs but do not propose any further detail.

There is a separate problem with the auto-generated plot for the rpa model noted in Ticket http://trac.sasview.org/ticket/871.

[smk78]

Trac update at 2019/03/27 11:03:27: smk78 commented:

Following a discussion at Code Camp IX this ticket is being closed as wontfix.

[smk78]

Trac update at 2019/03/27 11:03:40:

• smk78 changed resolution from "" to "wontfix"
• smk78 changed status from "new" to "closed"