fix VR for core_shell_cylinder, fractal_core_shell and hollow_cylinder

[pkienzle]

The VR function returns the volume of the whole and the volume of a part, creating the volume ratio:

    ratio = part / whole

The volume fraction used for the structure factor is then Vf/ratio.

This is appropriate when Vf refers to the volume fraction of shell rather than the volume fraction of the whole particle. Scaling by the volume ratio turns it into the volume fraction of the whole particle when calling the structure factor model.

Compared to sasview 3.x, we have the following VR functions in sasmodels:
rison with sasview 3.x

    core_shell_cylinder = shell / total [ 1 in sasview 3.x ]
    core_shell_sphere = 1 [ was 1 in sasview 3.x ]
    fractal_core_shell = shell / total [ model not in sasview 3.x? ]
    hollow_cylinder = total / shell [ was shell / total in sasview 3.x ]
    hollow_rectangular_prism = shell / total  [ was 1 in sasview 3.x ]
    hollow_rectangular_prism_thin_walls = surface area / total [ was 1 in sasview 3.x ]
    vesicle = shell / total [ was shell / total in sasview 3.x ]

    * core_shell_sphere has code for shell / total, but that was replaced with 1 when we added sesans support
    * hollow_cylinder is returning total/shell rather than shell/total
    * hollow prisms had ER and VR defined as 1 in 3.x

We should remove VR for core_shell_sphere, core_shell_cylinder and fractal_core_shell, and fix the hollow_cylinder ratio.

See also ticket #1030.

[butler]

aha .. yes that makes sense … never did quite understand the point of VR. We should check the latest documentation and update so it is clear (maybe it has been since I last looked)… and of course fix post haste.

The problem with nomenclature I guess is who we want to target. From the lab experimentalist's point of view the "shell" volume fraction is in fact the actual volume fraction (what else is there?!!) while from the point of view of the scattering theorist the real volume fraction will be the whole object. Actually the difference more generally is the volume fraction of the species doing the scattering (wherever inside a nominal object it is distributed) vs the effective volume fraction from the point of view of the interaction radius and of the normalization volume for the nominal object being used to create the form factor. This is usually a shell but I guess one could imagine other cases?

Indeed this is a classic gotcha when looking at things like large vesicles (I would say newbies but plenty of none newbies have been bitten - names shall remain redacted). At just a few volume percent (non charged system) you don't have to worry about interactions… true except that since all the lipid is actually in a shell the real volume fraction is 3 to 5 times what you put in (depending on radius) and so interactions become important much sooner than expected.

[richardh]

As discussed at code camp:

Note VR calculation is only used when model is multiplied by S(Q) - historically some confusion  has arisen as to when VR should be provided, which is only for hollow particles where the user knows the volume fraction of material in the shell rather than the whole particle.

product.py expects VR function to return part & whole volume in that order, thus as noted above hollow_cylinder is currently incorrect.

vesicle model uniquely has both scale and volfraction, but is using scale with VR correction if multiplied by S(Q), thus the correct behavior would only happen if volfraction is set to 1.0 when using S(Q), after discussion it was decided to edit vesicle model to conform with the other hollow particle models.

[pkienzle]

See ticket #1030

[GitHub <noreply@…>]

In 1a3c0c633570d13536dbdfce519aa921ffbff3fe/sasmodels:

Merge pull request #78 from SasView?/ticket-1160-VR

Ticket 1160 vr

Besides fixing the VR (removing from core_shell models and fixing hollow_cylinder) cleaned up a bunch of model documentation. Also realized that the 3 issues raised in ticket 1030 were mostly addressed so fixed last small docs issue as per Richard Heenan in order to close both tickets at once.

Closes #1160; closes #1030