Changeset 5f3c534 in sasmodels


Ignore:
Timestamp:
Mar 27, 2019 12:11:45 PM (6 years ago)
Author:
smk78
Branches:
master, core_shell_microgels, magnetic_model, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests
Children:
9947865
Parents:
055ec4f
Message:

Tweaks to docs for all S(q) models as described in #1187

Location:
sasmodels/models
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • sasmodels/models/hardsphere.py

    r0507e09 r5f3c534  
    11# Note: model title and parameter table are inserted automatically 
    2 r"""Calculate the interparticle structure factor for monodisperse 
     2r""" 
     3Calculates the interparticle structure factor for monodisperse 
    34spherical particles interacting through hard sphere (excluded volume) 
    4 interactions. 
    5 May be a reasonable approximation for other shapes of particles that 
    6 freely rotate, and for moderately polydisperse systems. Though strictly 
    7 the maths needs to be modified (no \Beta(Q) correction yet in sasview). 
     5interactions. This $S(q)$ may also be a reasonable approximation for  
     6other particle shapes that freely rotate (but see the note below),  
     7and for moderately polydisperse systems. 
     8 
     9.. note:: 
     10 
     11   This routine is intended for uncharged particles! For charged  
     12   particles try using the :ref:`hayter-msa` $S(q)$ instead. 
     13    
     14.. note:: 
     15 
     16   Earlier versions of SasView did not incorporate the so-called  
     17   $\beta(q)$ ("beta") correction [1] for polydispersity and non-sphericity.  
     18   This is only available in SasView versions 4.2.2 and higher. 
    819 
    920radius_effective is the effective hard sphere radius. 
    1021volfraction is the volume fraction occupied by the spheres. 
    1122 
    12 In sasview the effective radius may be calculated from the parameters 
     23In SasView the effective radius may be calculated from the parameters 
    1324used in the form factor $P(q)$ that this $S(q)$ is combined with. 
    1425 
    1526For numerical stability the computation uses a Taylor series expansion 
    16 at very small $qR$, there may be a very minor glitch at the transition point 
    17 in some circumstances. 
     27at very small $qR$, but there may be a very minor glitch at the  
     28transition point in some circumstances. 
    1829 
    19 The S(Q) uses the Percus-Yevick closure where the interparticle 
    20 potential is 
     30This S(q) uses the Percus-Yevick closure relationship [2] where the  
     31interparticle potential $U(r)$ is 
    2132 
    2233.. math:: 
    … …  
    2738    \end{cases} 
    2839 
    29 where $r$ is the distance from the center of the sphere of a radius $R$. 
     40where $r$ is the distance from the center of a sphere of a radius $R$. 
    3041 
    3142For a 2D plot, the wave transfer is defined as 
    … …  
    3849References 
    3950---------- 
     51 
     52.. [#] M Kotlarchyk & S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469 
    4053 
    4154.. [#] J K Percus, J Yevick, *J. Phys. Rev.*, 110, (1958) 1 
    … …  
    6376    [Hard sphere structure factor, with Percus-Yevick closure] 
    6477        Interparticle S(Q) for random, non-interacting spheres. 
    65     May be a reasonable approximation for other shapes of 
    66     particles that freely rotate, and for moderately polydisperse 
    67         systems. Though strictly the maths needs to be modified - 
    68     which sasview does not do yet. 
     78    May be a reasonable approximation for other particle shapes 
     79    that freely rotate, and for moderately polydisperse systems 
     80    . The "beta(q)" correction is available in versions 4.2.2 
     81    and higher. 
    6982    radius_effective is the hard sphere radius 
    7083    volfraction is the volume fraction occupied by the spheres. 

  • sasmodels/models/hayter_msa.py

    r0507e09 r5f3c534  
    11# Note: model title and parameter table are inserted automatically 
    22r""" 
    3 This calculates the structure factor (the Fourier transform of the pair 
    4 correlation function $g(r)$) for a system of charged, spheroidal objects 
    5 in a dielectric medium. When combined with an appropriate form factor 
    6 (such as sphere, core+shell, ellipsoid, etc), this allows for inclusion 
    7 of the interparticle interference effects due to screened coulomb repulsion 
    8 between charged particles. 
     3Calculates the interparticle structure factor for a system of charged,  
     4spheroidal, objects in a dielectric medium [1,2]. When combined with an  
     5appropriate form factor $P(q)$, this allows for inclusion of the  
     6interparticle interference effects due to screened Coulombic  
     7repulsion between the charged particles. 
    98 
    10 **This routine only works for charged particles**. If the charge is set to 
    11 zero the routine may self-destruct! For non-charged particles use a hard 
    12 sphere potential. 
     9.. note:: 
     10 
     11   This routine only works for charged particles! If the charge is set  
     12   to zero the routine may self-destruct! For uncharged particles use  
     13   the :ref:`hardsphere` $S(q)$ instead. 
     14    
     15.. note:: 
     16 
     17   Earlier versions of SasView did not incorporate the so-called  
     18   $\beta(q)$ ("beta") correction [3] for polydispersity and non-sphericity.  
     19   This is only available in SasView versions 4.2.2 and higher. 
    1320 
    1421The salt concentration is used to compute the ionic strength of the solution 
    15 which in turn is used to compute the Debye screening length. At present 
    16 there is no provision for entering the ionic strength directly nor for use 
    17 of any multivalent salts, though it should be possible to simulate the effect 
    18 of this by increasing the salt concentration. The counterions are also 
    19 assumed to be monovalent. 
     22which in turn is used to compute the Debye screening length. There is no  
     23provision for entering the ionic strength directly. **At present the  
     24counterions are assumed to be monovalent**, though it should be possible  
     25to simulate the effect of multivalent counterions by increasing the salt  
     26concentration. 
    2027 
    21 In sasview the effective radius may be calculated from the parameters 
     28Over the range 0 - 100 C the dielectric constant $\kappa$ of water may be  
     29approximated with a maximum deviation of 0.01 units by the empirical  
     30formula [4] 
     31 
     32.. math:: 
     33 
     34    \kappa = 87.740 - 0.40008 T + 9.398x10^{-4} T^2 - 1.410x10^{-6} T^3 
     35     
     36where $T$ is the temperature in celsius. 
     37 
     38In SasView the effective radius may be calculated from the parameters 
    2239used in the form factor $P(q)$ that this $S(q)$ is combined with. 
    2340 
    … …  
    3855 
    3956.. [#] J B Hayter and J Penfold, *Molecular Physics*, 42 (1981) 109-118 
     57 
    4058.. [#] J P Hansen and J B Hayter, *Molecular Physics*, 46 (1982) 651-656 
     59 
     60.. [#] M Kotlarchyk and S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469 
     61 
     62.. [#] C G Malmberg and A A Maryott, *J. Res. Nat. Bureau Standards*, 56 (1956) 2641 
    4163 
    4264Source 
    … …  
    5274* **Author:**  
    5375* **Last Modified by:**  
    54 * **Last Reviewed by:**  
     76* **Last Reviewed by:** Steve King **Date:** March 27, 2019 
    5577* **Source added by :** Steve King **Date:** March 25, 2019 
    5678""" 
    … …  
    7496 
    7597name = "hayter_msa" 
    76 title = "Hayter-Penfold rescaled MSA, charged sphere, interparticle S(Q) structure factor" 
     98title = "Hayter-Penfold Rescaled Mean Spherical Approximation (RMSA) structure factor for charged spheres" 
    7799description = """\ 
    78100    [Hayter-Penfold RMSA charged sphere interparticle S(Q) structure factor] 
    79         Interparticle structure factor S(Q)for a charged hard spheres. 
    80         Routine takes absolute value of charge, use HardSphere if charge 
    81         goes to zero. 
    82         In sasview the effective radius and volume fraction may be calculated 
    83         from the parameters used in P(Q). 
     101        Interparticle structure factor S(Q) for charged hard spheres. 
     102    This routine only works for charged particles! For uncharged particles  
     103    use the hardsphere S(q) instead. The "beta(q)" correction is available  
     104    in versions 4.2.2 and higher. 
    84105""" 
    85106 
    … …  
    93114    ["temperature",   "K",  318.16,   [0, 450],    "", "temperature, in Kelvin, for Debye length calculation"], 
    94115    ["concentration_salt",      "M",    0.0,    [0, inf], "", "conc of salt, moles/litre, 1:1 electolyte, for Debye length"], 
    95     ["dielectconst",  "None",    71.08,   [-inf, inf], "", "dielectric constant (relative permittivity) of solvent, default water, for Debye length"] 
     116    ["dielectconst",  "None",    71.08,   [-inf, inf], "", "dielectric constant (relative permittivity) of solvent, kappa, default water, for Debye length"] 
    96117    ] 
    97118# pylint: enable=bad-whitespace, line-too-long 

  • sasmodels/models/squarewell.py

    r0507e09 r5f3c534  
    11# Note: model title and parameter table are inserted automatically 
    22r""" 
    3 This calculates the interparticle structure factor for a square well fluid 
    4 spherical particles. The mean spherical approximation (MSA) closure was 
    5 used for this calculation, and is not the most appropriate closure for 
    6 an attractive interparticle potential. This solution has been compared 
    7 to Monte Carlo simulations for a square well fluid, showing this calculation 
    8 to be limited in applicability to well depths $\epsilon < 1.5$ kT and 
    9 volume fractions $\phi < 0.08$. 
     3Calculates the interparticle structure factor for a hard sphere fluid  
     4with a narrow, attractive, square well potential. **The Mean Spherical  
     5Approximation (MSA) closure relationship is used, but it is not the most  
     6appropriate closure for an attractive interparticle potential.** However,  
     7the solution has been compared to Monte Carlo simulations for a square  
     8well fluid and these show the MSA calculation to be limited to well  
     9depths $\epsilon < 1.5$ kT and volume fractions $\phi < 0.08$. 
    1010 
    1111Positive well depths correspond to an attractive potential well. Negative 
    1212well depths correspond to a potential "shoulder", which may or may not be 
    13 physically reasonable. The stickyhardsphere model may be a better choice in 
    14 some circumstances. Computed values may behave badly at extremely small $qR$. 
     13physically reasonable. The :ref:`stickyhardsphere` model may be a better  
     14choice in some circumstances. 
     15 
     16Computed values may behave badly at extremely small $qR$. 
     17 
     18.. note:: 
     19 
     20   Earlier versions of SasView did not incorporate the so-called  
     21   $\beta(q)$ ("beta") correction [2] for polydispersity and non-sphericity.  
     22   This is only available in SasView versions 4.2.2 and higher. 
    1523 
    1624The well width $(\lambda)$ is defined as multiples of the particle diameter 
    … …  
    1826 
    1927The interaction potential is: 
    20  
    21   .. image:: img/squarewell.png 
    2228 
    2329.. math:: 
    … …  
    2935    \end{cases} 
    3036 
    31 where $r$ is the distance from the center of the sphere of a radius $R$. 
     37where $r$ is the distance from the center of a sphere of a radius $R$. 
    3238 
    33 In sasview the effective radius may be calculated from the parameters 
     39In SasView the effective radius may be calculated from the parameters 
    3440used in the form factor $P(q)$ that this $S(q)$ is combined with. 
    3541 
    … …  
    4652.. [#] R V Sharma, K C Sharma, *Physica*, 89A (1977) 213 
    4753 
     54.. [#] M Kotlarchyk and S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469 
     55 
    4856Source 
    4957------ 
    … …  
    5664* **Author:**  
    5765* **Last Modified by:**  
    58 * **Last Reviewed by:**  
     66* **Last Reviewed by:** Steve King **Date:** March 27, 2019 
    5967* **Source added by :** Steve King **Date:** March 25, 2019 
    6068""" 
    … …  
    6472 
    6573name = "squarewell" 
    66 title = "Square well structure factor, with MSA closure" 
     74title = "Square well structure factor with Mean Spherical Approximation closure" 
    6775description = """\ 
    6876    [Square well structure factor, with MSA closure] 
    69         Interparticle structure factor S(Q)for a hard sphere fluid with 
    70         a narrow attractive well. Fits are prone to deliver non-physical 
    71         parameters, use with care and read the references in the full manual. 
    72         In sasview the effective radius will be calculated from the 
    73         parameters used in P(Q). 
     77        Interparticle structure factor S(Q) for a hard sphere fluid  
     78    with a narrow attractive well. Fits are prone to deliver non- 
     79    physical parameters; use with care and read the references in  
     80    the model documentation.The "beta(q)" correction is available  
     81    in versions 4.2.2 and higher. 
    7482""" 
    7583category = "structure-factor" 

  • sasmodels/models/stickyhardsphere.py

    r0507e09 r5f3c534  
    11# Note: model title and parameter table are inserted automatically 
    22r""" 
    3 This calculates the interparticle structure factor for a hard sphere fluid 
    4 with a narrow attractive well. A perturbative solution of the Percus-Yevick 
    5 closure is used. The strength of the attractive well is described in terms 
    6 of "stickiness" as defined below. 
    7  
    8 The perturb (perturbation parameter), $\epsilon$, should be held between 0.01 
    9 and 0.1. It is best to hold the perturbation parameter fixed and let 
    10 the "stickiness" vary to adjust the interaction strength. The stickiness, 
    11 $\tau$, is defined in the equation below and is a function of both the 
    12 perturbation parameter and the interaction strength. $\tau$ and $\epsilon$ 
    13 are defined in terms of the hard sphere diameter $(\sigma = 2 R)$, the 
    14 width of the square well, $\Delta$ (same units as $R$\ ), and the depth of 
    15 the well, $U_o$, in units of $kT$. From the definition, it is clear that 
    16 smaller $\tau$ means stronger attraction. 
     3Calculates the interparticle structure factor for a hard sphere fluid  
     4with a narrow, attractive, potential well. Unlike the :ref:`squarewell`  
     5model, here a perturbative solution of the Percus-Yevick closure  
     6relationship is used. The strength of the attractive well is described  
     7in terms of "stickiness" as defined below. 
     8 
     9The perturbation parameter (perturb), $\tau$, should be fixed between 0.01 
     10and 0.1 and the "stickiness", $\epsilon$, allowed to vary to adjust the  
     11interaction strength. The "stickiness" is defined in the equation below and is  
     12a function of both the perturbation parameter and the interaction strength.  
     13$\epsilon$ and $\tau$ are defined in terms of the hard sphere diameter $(\sigma = 2 R)$,  
     14the width of the square well, $\Delta$ (having the same units as $R$\ ),  
     15and the depth of the well, $U_o$, in units of $kT$. From the definition, it  
     16is clear that smaller $\epsilon$ means a stronger attraction. 
    1717 
    1818.. math:: 
    1919 
    20     \tau     &= \frac{1}{12\epsilon} \exp(u_o / kT) \\ 
    21     \epsilon &= \Delta / (\sigma + \Delta) 
     20    \epsilon     &= \frac{1}{12\tau} \exp(u_o / kT) \\ 
     21    \tau &= \Delta / (\sigma + \Delta) 
    2222 
    2323where the interaction potential is 
    … …  
    3131        \end{cases} 
    3232 
    33 The Percus-Yevick (PY) closure was used for this calculation, and is an 
    34 adequate closure for an attractive interparticle potential. This solution 
     33The Percus-Yevick (PY) closure is used for this calculation, and is an 
     34adequate closure for an attractive interparticle potential. The solution 
    3535has been compared to Monte Carlo simulations for a square well fluid, with 
    3636good agreement. 
    3737 
    38 The true particle volume fraction, $\phi$, is not equal to $h$, which appears 
    39 in most of the reference. The two are related in equation (24) of the 
    40 reference. The reference also describes the relationship between this 
    41 perturbation solution and the original sticky hard sphere (or adhesive 
    42 sphere) model by Baxter. 
    43  
    44 **NB**: The calculation can go haywire for certain combinations of the input 
    45 parameters, producing unphysical solutions - in this case errors are 
    46 reported to the command window and the $S(q)$ is set to -1 (so it will 
    47 disappear on a log-log plot). Use tight bounds to keep the parameters to 
    48 values that you know are physical (test them) and keep nudging them until 
    49 the optimization does not hit the constraints. 
    50  
    51 In sasview the effective radius may be calculated from the parameters 
     38The true particle volume fraction, $\phi$, is not equal to $h$ which appears 
     39in most of reference [1]. The two are related in equation (24). Reference  
     40[1] also describes the relationship between this perturbative solution and  
     41the original sticky hard sphere (or "adhesive sphere") model of Baxter [2]. 
     42 
     43.. note:: 
     44 
     45   The calculation can go haywire for certain combinations of the input 
     46   parameters, producing unphysical solutions. In this case errors are 
     47   reported to the command window and $S(q)$ is set to -1 (so it will 
     48   disappear on a log-log plot!). 
     49    
     50   Use tight bounds to keep the parameters to values that you know are  
     51   physical (test them), and keep nudging them until the optimization  
     52   does not hit the constraints. 
     53 
     54.. note:: 
     55 
     56   Earlier versions of SasView did not incorporate the so-called  
     57   $\beta(q)$ ("beta") correction [3] for polydispersity and non-sphericity.  
     58   This is only available in SasView versions 4.2.2 and higher. 
     59    
     60In SasView the effective radius may be calculated from the parameters 
    5261used in the form factor $P(q)$ that this $S(q)$ is combined with. 
    5362 
    … …  
    6574.. [#] S V G Menon, C Manohar, and K S Rao, *J. Chem. Phys.*, 95(12) (1991) 9186-9190 
    6675 
     76.. [#] R J Baxter, *J. Chem. Phys.*, 49 (1968), 2770-2774 
     77 
     78.. [#] M Kotlarchyk and S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469 
     79 
    6780Source 
    6881------ 
    … …  
    7588* **Author:**  
    7689* **Last Modified by:**  
    77 * **Last Reviewed by:**  
     90* **Last Reviewed by:** Steve King **Date:** March 27, 2019 
    7891* **Source added by :** Steve King **Date:** March 25, 2019 
    7992""" 
    … …  
    8598 
    8699name = "stickyhardsphere" 
    87 title = "Sticky hard sphere structure factor, with Percus-Yevick closure" 
     100title = "'Sticky' hard sphere structure factor with Percus-Yevick closure" 
    88101description = """\ 
    89102    [Sticky hard sphere structure factor, with Percus-Yevick closure] 
    90         Interparticle structure factor S(Q)for a hard sphere fluid with 
    91         a narrow attractive well. Fits are prone to deliver non-physical 
    92         parameters, use with care and read the references in the full manual. 
    93         In sasview the effective radius will be calculated from the 
    94         parameters used in P(Q). 
     103        Interparticle structure factor S(Q) for a hard sphere fluid  
     104    with a narrow attractive well. Fits are prone to deliver non- 
     105    physical parameters; use with care and read the references in  
     106    the model documentation.The "beta(q)" correction is available  
     107    in versions 4.2.2 and higher. 
    95108""" 
    96109category = "structure-factor" 
    … …  
    107120     "volume fraction of hard spheres"], 
    108121    ["perturb", "", 0.05, [0.01, 0.1], "", 
    109      "perturbation parameter, epsilon"], 
     122     "perturbation parameter, tau"], 
    110123    ["stickiness", "", 0.20, [-inf, inf], "", 
    111      "stickiness, tau"], 
     124     "stickiness, epsilon"], 
    112125    ] 
    113126 
Note: See TracChangeset for help on using the changeset viewer.