shape2sas 2.8.0

Shape2SAS

version 2.8

Shape2SAS simulates small-angle x-ray scattering (SAXS) from user-defined shapes. The models are build from geometrical subunits, e.g., a dumbbell constructed from a cylinder and two translated spheres. The shape is filled with points and the scattering is calculated by a Debye sum.

Table of Contents

• Installation
  • Other dependencies
• Run Shape2SAS
  • Available subunits (table)
  • Output files
• Examples
  • Example 1: More dimensions - cylinder
  • Example 2: Multiple subunits - dumbbell
  • Example 3: Structure factors - repulsion and aggregation
    • Available Structure factors (table)
  • Example 4: Several models
    • The compare script (table)
  • Example 5: Polydispersity
  • Example 6: Multi-contrast particle - cores-shell
  • Example 7: Rotation and translation - V-shape
    • Known bug for COM input and solution
  • Example 8: Number of points - accuracy-vs-runtime
  • Example 9: Spin-echo SANS - repulsion in real space
  • Example 10: Mixtures - small and large spheres
    • The mixture script (table)
  • Example 11: Fit experimental data - sphere sizes
• Shape2SAS inputs
  • Mandatory inputs
  • Model-dependent inputs
  • General inputs
  • Plot-related inputs
  • Fit-related inputs
• GUI
• Credit
  • Contributors
• Notes

Installation

Install Python3 (you need python3.8 or newer) and pip, then install Shape2SAS by:

pip install shape2sas

developer version (beta)

• Install necessary python packages (see other dependencies).
• Download the repository by clicking the green "<> Code" button and "Download ZIP". Extract the ZIP file where you want Shape2SAS to be installed.
• Install the dependencies listed in tools/dependencies.txt by running the command: python -m pip install -r tools/dependencies.txt.

Back to Table of contents

Run Shape2SAS

Shape2sas runs via a terminal (Linux) or a command prompt (Windows). At least two inputs are required: --subunit (or -s) and --dimension (or -d). The scattering from a sphere with radius of 50 Å can be simulated with:

shape2sas --subunit sphere --dimension 50

or You may also use the shorter input:

shape2sas -s sphere -d 50

and the results can be opened with

open Model_0/plot_Model_0.png Model_0/points_Model_0.png

which is the output plot of SAXS data, and the 2D representation of the sphere (Model_0 is the default model name if none is provided).

Back to Table of contents

Output files

• Iq_<model_name>.dat, Isim_<model_name>.dat: theoretical and simulated SAS data
• pr_<model_name>.dat: pair distribution
• Sq_<model_name>.dat: structure factor (just unity if no structure factor is opted for).
• plot.png: plot of p(r), theoretical data and simualated SAS data
• points_<model_name>.png: point cloud, 2D projection
• <model_name>.pdb: points cloud in 3D, Proten data bank format, can be opened in PyMOL, Mol* 3D viewer, etc.
• sesans.png: plot of sesans data (if opted for)
• G_<model_name>.dat, G_sim_<model_name>.dat: theoretical and simulated SESANS data (if opted for)
• shape2sas.log: log file, same as the terminal output

Back to Table of contents

Subunits

The following subunits are currently available:

input order is important.
names are not case-sensitive, and underscores are ignored, so for example Hollowsphere or hollow_sphere or hollowSphere or HoLlo_w_sPh_Ere all give the same subunit.
see superellipsoid sasview model

Back to Table of contents

Developer mode

Navigate to the extracted directory containing shape2sas.py:

cd <PATH-TO-DIRECTORY>

run with

python shape2sas.py --subunit sphere --dimension 50

Examples

A list of all options can be found below all the examples.

Example 1: More dimensions - cylinder

A model of a cylinder with radius 50 Å and length 300 Å is simulated, and named "cylinder". The name is used in plots and output filenames:

shape2sas --subunit cylinder --dimension 50,300 --model_name cylinder
open cylinder/plot_cylinder.png cylinder/points_cylinder.png

Dimensions should be given as a list without space, or between quotation marks (then spaces are allowed):

shape2sas --subunit cylinder --dimension "50, 300" --model_name cylinder
open cylinder/plot_cylinder.png cylinder/points_cylinder.png

If quotation marks are used, commas may be omitted from the list:

shape2sas --subunit cylinder --dimension "50 300" --model_name cylinder
open cylinder/plot_cylinder.png cylinder/points_cylinder.png

Example 1: Shape2SAS simulation showing the "side" and "bottom" of the cylinder model and simulated SAXS with noise.

Back to Table of contents

Example 2: Multiple subunits - dumbbell

A model can be built of several subunits. For example, a dumbbell can be built by three subunits: two spheres with radius 25 Å displaced from the origin by 50 Å along the z-axiz, and one cylinder with radius of 10 Å and length of 100 Å, aligned along the z axis (default direction):

shape2sas --subunit sphere,sphere,cylinder --dimension 25 25 10,100 --com 0,0,-50 0,0,50 0,0,0 --Npoints 6000 --model_name dumbbell
open dumbbell/plot_dumbbell.png dumbbell/points_dumbbell.png

If you use quotation marks for input with several values, for example --subunit, then spaces are allowed, also in the name (space is replaced with underscore in file names):

shape2sas --subunit "sphere, sphere, cylinder" --dimension "25" "25" "10, 100" --com "0, 0, -50" "0, 0, 50" "0, 0, 0" --model_name "my dumbbell"
open my_dumbbell/plot_my_dumbbell.png my_dumbbell/points_my_dumbbell.png

and, as mentioned in Example 1, you may omit commas if you use quotation marks:

shape2sas --subunit "sphere, sphere, cylinder" --dimension 25 25 "10 100" --com "0 0 -50" "0 0 50" "0 0 0" --model_name "my dumbbell"
open my_dumbbell/plot_my_dumbbell.png my_dumbbell/points_my_dumbbell.png

Example 2: Dumbbell model and simulated SAXS data.

Back to Table of contents

Example 3: Structure factors - repulsion and aggregation

Structure factors can be added. This will affect the calculated scattering but not the displayed $p(r)$. Below a sample of ellipsoids with semi-axes 50, 60, and 50 Å with hard-sphere repulsion with volume fraction of 0.1 and hard-sphere radius of 60 Å:

shape2sas --subunit ellipsoid --dimension 50,60,50 --S HS --S_par 0.1,60 --model_name ellipsoid_HS
open ellipsoid_HS/plot_ellipsoid_HS.png ellipsoid_HS/points_ellipsoid_HS.png

Aggregation can also be simulated through a structure factor. Below a sample containing aggregates wirh effective radius of 60, 90 particles per aggregate. A fraction of 10% of the particles are aggregated, the rest are monomeric:

shape2sas --subunit ellipsoid --dimension "50, 60, 50" --S aggregation --S_par 60,90,0.1 --model_name ellipsoid_aggr
open ellipsoid_aggr/plot_ellipsoid_aggr.png ellipsoid_aggr/points_ellipsoid_aggr.png

Example 3: Ellipsoids with a hard-sphere structure factor (left) or with aggregation (right).

Back to Table of contents

Structure factors

The following structure factors are implemented

^* provided with flag --S_par (or -Sp) - input order is important.
^** structure factor names are also not case-sensitive.

Back to Table of contents

Example 4: Several models

Several models can be compared using the compare script.

Spheres and cylinders:

shape2sas --subunit sphere --dimension 50 --model_name sphere
shape2sas --subunit cylinder --dimension 20,300 --model_name cylinder
shape2sas-compare --model_names sphere,cylinder --name sph_cyl --plot_points

Note that if models are already calculated, you do not need to calculate them again. For example, you could add an ellipsoid to the comparison by

python shape2sas --subunit ellipsoid --dimension 30,30,100 --model_name ellipsoid
shape2sas-compare --model_names sphere,cylinder,ellipsoid --name sph_cyl_ellips --plot_points

Alternatively (legacy, not recommended), comparison can be done in one line:

python shape2sas.py --subunit sphere --dimension 50 --model_name sphere --subunit cylinder --dimension 20,300 --model_name cylinder 
open cylinder/plot_cylinder.png sphere/points_sphere.png cylinder/points_cylinder.png

Ellipsoids with or without a hard-sphere structure factor:

shape2sas -s ellips -d 50,60,50 -m ellipsoid
shape2sas -s ellips -d 50,60,50 -S HS -Sp 0.05,60 -m ellipsoid_HS
shape2sas-compare -m ellipsoid,ellipsoid_HS

Increasing sphere size:

shape2sas --subunit sphere --dimension 20 --model_name sph20 
shape2sas --subunit sphere --dimension 50 --model_name sph50 
shape2sas --subunit sphere --dimension 80 --model_name sph80 
shape2sas-compare -m sph20,sph50,sph80

Example 4: Scattering from spheres of increasing size.

Back to Table of contents

The compare script

The compare.py script compares results from calculated shape2sas models, using the output files. Inputs are given in the table below, or by typing shape2sas-compare -h

for usage, see Example 4.

compare.py output files:

<name>_compare.png: p(r), theoretical I and simulated I (with noise) for selected models <name>_compare_points.png: 2D projections of the models (if opted for by the `--plot_points' flag)

Back to Table of contents

Example 5: Polydispersity

Sphere with radius of 40 Å and relative polydispersity of 20% are here compared to monodisperse spheres with the same radius:

shape2sas --subunit sphere --dimension 40 --polydispersity 0.15 --model_name sphere_pd 
shape2sas --subunit sphere --dimension 40 --model_name sphere
shape2sas-compare.py -m sphere,sphere_pd

Example 5: Scattering from monodisperse versus polydisperse spheres. Polydispersity is also reflected in the $p(r)$

Back to Table of contents

Example 6: Multi-contrast particle - core-shell

The contrast (excess scattering length density, sld) of each subunit can be adjusted to form multi-contrast particles. For example, a core-shell sphere with core ΔSLD of -1 and shell ΔSLD of 2 may be simulated:

shape2sas --subunit sphere,sphere --dimension 30 45 --sld -1 1 --model_name core_shell
open core_shell/plot_core_shell.png core_shell/points_core_shell.png

The small (radius 30-Å) and the large (radius 45 Å) sphere overlap. In that case, the overlapping points of the latter model are excluded. So order is important! The following will just give the scattering of the large sphere, as all points from the smaller sphere are excluded:

shape2sas --subunit sphere,sphere --dimension 45 30 --sld 1 -1 --model_name "not core shell just a sphere"
open not_core_shell_just_a_sphere/plot_not_core_shell_just_a_sphere.png not_core_shell_just_a_sphere/points_not_core_shell_just_a_sphere.png

The spherical core-shell model can also be modelled with a sphere for the core and a hollow sphere for the shell. Or, it can be modelled with the two solid spheres by disabling exclusion of overlapping points, but also changing the contrast of the small sphere to -2. The results are the same, but the third method is less effective (accuracy vs number of points).

shape2sas --subunit sphere,sphere --dimension 30 45 --sld -1 1 --exclude_overlap True --model_name core_shell_1 
shape2sas --subunit sphere,hollow_sphere --dimension 30 45,30 --sld -1 1 --exclude_overlap True --model_name core_shell_2 
shape2sas --subunit sphere,sphere --dimension 30 45 --sld -2 1 --exclude_overlap False --model_name core_shell_3
shape2sas-compare -m core_shell_1,core_shell_2,core_shell_3 -p

Example 7: Spherical core-shell particles with core ΔSLD of -1 and shell ΔSLD of 1, simulated in three different ways

Back to Table of contents

Example 7: Rotation and translation - V-shape

A model of a "V" is formed with two 100-Å long cylinders with radius of 20 Å, which are rotated 45$\degree$ in each direction around the x-axis. The first cylinder i displaced by 50 Å along the y-axis (com, for centre-of-mass translation). The rotation is also around the center of mass

shape2sas --subunit "cylinder, cylinder" --dimension "20, 100" "20, 100" --rotation "45, 0, 0" "-45, 0, 0" --com "0, -50, 0" "0, 0, 0" --model_name cylinders_rotated
open cylinders_rotated/plot_cylinders_rotated.png cylinders_rotated/points_cylinders_rotated.png

By default each subunit is rotated around its own centre. Use --rotation_points (or -rotp) to rotate around another point instead, given in the subunit's own frame. For example, to swing the second cylinder around one of its ends rather than its middle:

shape2sas --subunit "cylinder, cylinder" --dimension "20, 100" "20, 100" --rotation "0, 0, 0" "0, 90, 0" --rotation_points "0, 0, 0" "0, 0, 50" --model_name cylinders_hinged

The rotation is applied before the --com translation, so the two can be combined freely.

Known bug for COM/Rotation input, and solution/work-around

If the COM translation x-coordinate is negative, you (may) get an error (e.g., --com "-50, 0, 0" "0, 0, 0" or --com "0, 0, 0" "-50, 0, 0"). This can be circumvented by adding a space before the minus sign (e.g., --com " -50, 0, 0" "0, 0, 0"). Quotation marks are needed in this workaround.

Example 7: Simulated SAXS for two cylinders rotated around the x-axis with $\alpha \pm 45\degree$.

Back to Table of contents

Example 8: Number of points - accuracy vs runtime

The data are simulated using a finite number of points ro represent the structures. Default is 5000 per model. This is a balance between accuracy and speed. As --Npoints is a global parameter, it cannot be selected separately for each model, therefore, three separate runs must be done:

shape2sas --subunit ellipsoid --dimension 40,40,60 --model_name ellipsoids500 --Npoints 500
shape2sas --subunit ellipsoid --dimension 40,40,60 --model_name ellipsoids5000 --Npoints 5000
shape2sas --subunit ellipsoid --dimension 40,40,60 --model_name ellipsoids50000 --Npoints 50000
shape2sas-compare --model_names ellipsoids500,ellipsoids5000,ellipsoids50000 --name Npoints

Computation time depends on hardware, but increases with the number of points. However, the accuracy also increases, as the number of points increases, and the simulated curve is accurate up to a higher value of q.

Example 8: Ellipsoids simulated with 500, 5000 or 50,000 points per model

Back to Table of contents

Example 9: Spin-echo SANS - repulsion in real space

Spin-echo SANS (SESANS) is a related technique, and SAS data can be converted to SESANS data by a Henckel transformation. SESANS data is in real space, so easier to interpret - similar to the pair distribution (p(r)) in SAS.

The q-range is extended and sampled with many points to make the tranformation more accurate, therefore, the normal qmin, qmax and qpoints parameters are not used.

Spheres with or without hard-sphere intearaction in SESANS:

shape2sas --sesans --subunit sphere --dimension 50 --model_name sphere 
shape2sas --sesans --subunit sphere --dimension 50 --S HS --S_par 0.1,60 --model_name sphere_HS
shape2sas-compare -m sphere,sphere_HS --sesans

One sphere (radius 250 Å) vs two spheres separated by 1000 Å:

shape2sas --sesans --subunit sphere --dimension 250 --model_name sphere 
shape2sas --sesans --subunit sphere,sphere --dimension 250 250 --com 0,-500,0 0,500,0 --model_name two_spheres
shape2sas-compare -m two_spheres,sphere --sesans

Example 9: SESANS spheres with or without hard-sphere interaction

Back to Table of contents

Example 10: Mixtures - small and large spheres

If you have different particles on solution and the do not interact, you can model this as a mixture. This can be modelled with the mixture script. E.g a sample with non-interacting small and large spheres. The fraction of large is set to 5%:

shape2sas -s sph -d 30 -m sph_small
shape2sas -s sph -d 60 -m sph_large
shape2sas-mixture -m sph_small,sph_large -f 95,5

Back to Table of contents

The mixture script

The mixture.py script calculate scattering from a mixture of non-interacting particles, using pre-calculated output files from shape2sas. Inputs are given in the table below, or by typing shape2sas-mixture -h

for usage, see Example 4.

mixture.pyoutput files:

mixture_<name>/pr_<name>.dat, mixture_<name>/Iq_<name>.dat, mixture_<name>/Isim_<name>.dat: p(r), theoretical I and simulated I (with noise) for mixture of selected models (using --model_name optioin), at selected fractions (using the --fractionoption)
mixture_<name>/<name>.png: plots of the above, campared with the p(r) and scattering from the components.

Back to Table of contents

Example 11: Fit experimental data - sphere sizes

With the --data (or -dat) option, the calculated scattering can be compared with experimental (or simulated) data. For example, first simulate SAXS data from sphere with a radius of 40 Å:

shape2sas --subunit sphere --dimension 40 --model_name sph40

then use this as the experimental data to compare with spheres of varying sizes:

shape2sas -s sph -d 80 -m sph80 -s sph -d 20 -m sph20 -s sph -d 35 -m sph35 -dat sph40/Isim_sph40.dat
open fit.png

The point is of course to compare with actual measured data. Automatic fitting is not available (yet) - only data comparison and 'manual' fitting.

Back to Table of contents

Shape2SAS inputs

Shape2SAS has two types of inputs: model-dependent inputs, that only affect the specific model in question, and general inputs that affects all models.

Mandatory inputs (model-dependent):

Model-dependent (and optional) inputs:

General (and optional) inputs:

Plot-related (and optional) inputs:

Back to Table of contents

Fit-related (and optional) inputs:

Back to Table of contents

GUI

you can run Shape2SAS as a webapp or through SasView, see sastools.org/shape2sas (newest features may not be available in the GUI).

Back to Table of contents

Credit

If useful for your work, please cite our paper:

Larsen, A. H., Brookes, E., Pedersen, M. C. & Kirkensgaard, J. J. K. (2023). Shape2SAS: a web application to simulate small-angle scattering data and pair distance distributions from user-defined shapes. Journal of Applied Crystallography 56, 1287-1294
https://doi.org/10.1107/S1600576723005848

Contributors

• Andreas Haahr Larsen: main developer
• Thomas Bukholt Hansen: batch script mode, including class structure and documentation
• Lassi Tiihonen: SESANS add-on
• Kristian Lytje: pypi packaging, AUSAXS inclusion, code clean-up

Back to Table of contents

Notes

Generally, the local Shape2SAS version has been built such that the repetition of the same flag from model dependent parameters will start a new model. Therefore, the different subunits associated with single model should all be written after the "--subunit" flag as well as their dimensions, displacement, polydispersity and so forth for their respective flag. The order of the subunits written in the "--subunit" flag for the model is important, as other parameters that are associated with each subunit in model should follow the same order. Likewise, when giving dimensions to a subunit, this should follow the order specified in the table of subunits.

Back to Table of contents