Inconsistent use of volume fraction in vesicle model

[gnsmith]

Describe the bug I will include screenshots from a selected simulation to illustrate the bug.

The "vesicle" model (category: sphere) includes a term for volume fraction of shell material. As far as I can tell from the documentation (https://www.sasview.org/docs/user/models/vesicle.html), this is done for volume normalisation to reduce the scattering to that from the shell only. When adding a structure factor, this volume fraction is then taken as the structure factor volume fraction. However, while they have the same names, they are conceptually different. The volume fraction (for form factor), as described in the documentation, is the fraction of material added to the system. The volume fraction (for structure factor) needs to be the volume of the shell and the core, as the vesicles will fill up the entire volume (4/3piR_tot^3).

Using the values I put in this simulation and taking the sphere-equivalent volume of the shell, this means that the real volume fraction for the structure factor should be 1.42x that inputted. This will obviously differ for different combinations of radius and thickness.

To Reproduce Steps to reproduce the behavior:

1. Change Fit panel to the correct model, Category:Sphere and Model name:vesicle.
2. Simulate scattering without a structure factor.
3. Add in a structure factor model. The volfraction will not change.

Expected behavior I can see two possibilities.

• There can be be two volume fractions: one for volume normalisation and one for the structure factor.
• One of these volume fractions can be calculated and scaled from the known inputs. The first one would be more flexible, as it would allow units to override the calculations, but it would be a bit unsightly, requiring two terms called volume fraction. The opposite is true of the second.

Screenshots Entered in-line above.

SasView version (please complete the following information):

• Version: 5.0.6 release

Operating system (please complete the following information):

• OS: Windows 10

Additional context Just so that you can check my math, here are the values for volumes that I calculated using my inputs.

Volume core (radius) = 4/3pi200^3 = 3.35e7 Volume total (radius+thickness) = 4/3pi(200+100)^3 = 1.13e8 Volume shell (v_total-v_core) = 7.96e7

Rescaling of volume fraction for v_total = 1.13e8/7.96e7 = 1.42

Corrected volume fraction = 1.42*0.20 = 0.28

[gnsmith]

Here is the project file that I was using. vesicle_pqsq.json

[smk78]

@gnsmith did you read https://www.sasview.org/docs/user/qtgui/Perspectives/Fitting/fitting_sq.html ? It seems to imply that the 'correction' you mention is either performed automatically or (if not) can be applied through scale (essentially your second bullet)?

[murphyryanp]

@gnsmith: I was confused by this same issue a while ago. I think sasmodels is calculating the total (or excluded) volume fraction based on the shell volume fraciton. I was confused why the parameter "volfraction" is not explicitly called something distinct, like "shell_volfraction", to avoid confusion on whether the S(q) is indeed using the proper volfraction.

To visually confirm this is the case, I've plotted below a core-shell sphere model (orange) and vesicle model (blue), where the core_shell_sphere has core SLD = solvent SLD. I used the same parameters as you did in your vesicle example, and then plotted the results against a core-shell sphere with volume fraction 0.2 (results should be different) and 0.2839 (results should be identical).

Results with core_shell_volfraction = 0.2 and vesicle_volfraction = 0.2. These should be different in P(q) [top] and S(q) [bottom] and they are.

Results with core_shell_volfraction = 0.2839 and vesicle_volfraction = 0.2. These should be identical in P(q) [top] and S(q) [bototm], and they visually appear to be the same.

In short, I think the volfraction is being recalculated into the total volume fraction (behind the scenes) for purposes of the structure factor. I was still confused by the chosen parameter name!

[gnsmith]

Thank you for your input.

@smk78 I did very carefully read the documentation on the vesicle model https://www.sasview.org/docs/user/models/vesicle.html but didn't see anything about this. I did not read the documentation on Fitting Models with Structure Factors, but I can see it is there. Just to note, I did understand what the documentation was trying to say, but it took me a couple reads to follow what the paragraph was saying.

@murphyryanp It is reassuring to see what I'm not the only one who stumbled upon this! Your simulated data convince me that SasView is refactoring the inputted volume fraction to give a whole particle volume fraction.

The question for the developers is whether anything should be done here or whether you the application and the documentation are clear enough.

I did think to look at the documentation, and while I hope other users would, I expect that not all will. I did not think to look at the Structure Factor documentation, so perhaps clarification on the vesicle model documentation with a link to the Structure Factor documentation is an easy win.

Different people will think differently about what the "volume fraction" should be, and I don't think you could predict what everyone would think. Coming to a vesicle model from filled colloids, I would always think of a volume fraction as the amount of stuff within the outer radius. I can see how someone would come to it the other way, if they were primarily concerned with making the samples (how much stuff did I put in my solvent). A more flexible and clearer possibility might be to rename volfraction to shell_volfraction (in form factor modelling) and to add a parameter called sq_volfraction when modelling structure factors, which could automatically be calculated like the radius_effective is, or overridden if the user wanted to. This would make it possible to deal with for situations where effective volume fractions are greater than the shell volume fractions; for instance, if the vesicles had a low scattering stabilizer that could be excluded from the intensity but not the particle size. At the moment, this would require adjusting a refactored version of the volfraction. I don't know if this would mess up other parts of the calculation engine though.

I guess the options, and this is for developers to consider.

• Leave as is and trust users to read documentation.
• Update vesicle documentation to include information about hollow particles and link to Fitting Models with Structure Factors page.
• Divide volume fraction inputs into two with different names and include both in the vesicle fitting window.