Calculator

sinccity.GenericScatteringCalculator

Orientationally averaged I(q) of a structure, by the Debye formula.

The nuclear, 1D part of SasView's Generic Scattering Calculator::

w_j  = (sld_j - sld_solvent * 1e-6) * volume_j
I(q) = scale * 1e8 * D(q) / V_norm + background
D(q) = sum_jk w_j w_k sin(q r_jk) / (q r_jk)

V_norm is the volume of the points that scatter (w != 0) unless normalisation_volume is set. For space-filling pixels and cells, scale is then a volume fraction, as in sasmodels.

The kernel parameter picks how D(q) is summed; see set_params. The lattice, histogram and average kernels first build a distance spectrum that does not depend on the solvent; the last one is kept, so a change of sld_solvent, scale, background or normalisation_volume costs only the sums over q.

Example

gsc = GenericScatteringCalculator('particle.sld') gsc.set_params(sld_solvent=6.34) profile = gsc.calculate() gsc.plot_profile()

profile property

profile: ScatteringProfile | None

The result of the last calculate(), cleared by every setter.

load_structure

load_structure(path, **reader_options: Any) -> Structure

Read a PDB, GRO, SLD or VTK file and make it the current structure.

Parameters:

Name	Type	Description	Default
path		The structure file.	required
**reader_options	Any	As sinccity.load takes them.	{}

set_structure

set_structure(structure: Structure) -> None

Use an existing Structure, for example one from sinccity.load.

set_q_grid

set_q_grid(qmin: float = 0.0003, qmax: float = 0.3, npoints: int = 30, *, spacing: str = 'log') -> None

Build the q grid: npoints from qmin to qmax (1/Å), log or linear.

Unlike SasView, qmin does not follow qmax; set_q_grid(qmax=0.5) keeps qmin = 3e-4.

set_q

set_q(q) -> None

Use explicit q values (1/Å): positive, finite and increasing.

set_params

set_params(*, scale=_UNSET, background=_UNSET, sld_solvent=_UNSET, normalisation_volume=_UNSET, deuterated=_UNSET, kernel=_UNSET, histogram_bin=_UNSET, size_pd=_UNSET, size_pd_n=_UNSET, size_pd_nsigma=_UNSET) -> None

Set any of the calculation parameters; the others are kept.

Parameters:

Name	Type	Description	Default
scale		Multiplies I(q); >= 0.	_UNSET
background		Flat background, 1/cm; >= 0, because a computed curve has no subtraction residue to correct.	_UNSET
sld_solvent		Solvent SLD in 10⁻⁶ Å⁻², as in every sasmodels model (D2O is 6.34). SasView's calculator takes Å⁻² instead.	_UNSET
normalisation_volume		V_norm in ų, or 'auto' for the volume of the points that scatter. SasView calls this field total_volume.	_UNSET
deuterated		Residue names whose hydrogens count as D, applied with Structure.deuterated at calculate(); None or () for none.	_UNSET
kernel		How D(q) is summed. 'auto' (the default): 'lattice' for pixels on a lattice whose padded grid fits, else 'histogram'. 'lattice': FFT autocorrelation, exact. 'histogram': pairs counted by distance, exact to about 1e-4. 'average': the squared orientation-averaged amplitude about the bounding-box centre, exact only for spherically symmetric structures, with time linear in the points. 'pairs': every pair at every q, exact to the last digit.	_UNSET
histogram_bin		Bin width of the histogram kernel, Å, or 'auto' for min(0.01, 1e-3 / (q_max * f_max)), f_max the largest size factor.	_UNSET
size_pd		Relative standard deviation of the size of the whole structure (a Gaussian, as sasmodels' radius_pd); 0 is one size.	_UNSET
size_pd_n		Number of sizes, >= 1.	_UNSET
size_pd_nsigma		Half-range of the sizes in standard deviations, > 0.	_UNSET

calculate

calculate(*, progress: Callable[[float], bool | None] | None = None, label: str | None = None) -> ScatteringProfile

Compute I(q) on the current grid and return a ScatteringProfile.

Parameters:

Name	Type	Description	Default
progress	Callable[[float], bool | None] | None	Optional callback for long pair passes. It receives the completed fraction; returning True stops the calculation with CalculationInterrupted, leaving the previous state intact.	None
label	str | None	The curve's name; the structure file's name by default.	None

calculate_series

calculate_series(series: list[dict[str, Any]], *, progress: Callable[[float], bool | None] | None = None) -> list[ScatteringProfile]

Compute one profile per entry of series, on the current structure and q grid.

Each entry is {'label': ..., 'params': {...}}: set_params keys that override the current parameters for that entry only. Every entry is checked before anything runs. Entries run grouped by deuteration and kernel, so the pair pass runs once per group, and come back in the order given. A series is plain JSON, so get_settings() plus a series is a task another process runs with from_settings(settings).calculate_series(series).

Afterwards the parameters are those before the call, and profile is that of the last entry.

Parameters:

Name	Type	Description	Default
series	list[dict[str, Any]]	The entries.	required
progress	Callable[[float], bool | None] | None	Receives the completed fraction of the whole series; returning True stops it with CalculationInterrupted and leaves the parameters and profile as they were.	None

Raises:

Type	Description
ValueError	Naming the entry that is not a dict, or whose key or value is not allowed, including deuterated residue names the structure lacks.

describe

describe() -> None

Print the structure, the q grid and the parameters.

plot_points

plot_points(**kwargs: Any)

Draw the structure's points as they scatter.

Zero-contrast points use the current solvent, and the deuterated hydrogens have the SLD of D.

plot_profile

plot_profile(*, data=None, log_scale: bool = True, show: bool | None = None)

Plot the current profile, optionally over measured data (a Data1D).

get_settings

get_settings() -> dict[str, Any]

A JSON-serialisable record of the source, grid, parameters and versions.

A structure no reader made (from_arrays, or a copy derived from a file) is recorded as 'in-memory', which from_settings refuses; a derived copy also records derived_from, for information only.

from_settings classmethod

from_settings(settings: dict[str, Any]) -> GenericScatteringCalculator

Rebuild a calculator from get_settings(), warning about what changed.

sinccity.ScatteringProfile dataclass

A computed I(q) with everything needed to know how it was made.

Attributes:

Name	Type	Description
q	ndarray	Momentum transfer, 1/Å.
intensity	ndarray	I(q), 1/cm.
normalisation_volume	float	The volume V_norm the Debye sum was divided by, ų; nan when nothing scatters and no volume was set.
normalisation	str	'active-volume' (the default) or 'explicit'.
n_zero_contrast	int	Points whose SLD equals the solvent's.
method	str	Kernel used: 'lattice', 'histogram', 'average', 'pairs', or 'none' when nothing scatters.
histogram_bin	float | None	The histogram bin used, Å; None for other kernels.
n_sizes	int	Number of size factors summed (1 without polydispersity).
label	str	The curve's name; the structure file's name unless given.
deuterated	tuple[str, ...]	The residue names whose hydrogens counted as D.
notes	tuple[str, ...]	Warnings raised while reading and calculating.
elapsed	float	Calculation time, s.

params property

params: dict[str, Any]

The calculator's parameters (set_params), as set.

structure_summary property

structure_summary: dict[str, Any]

Source, format, kind, size and reader notes of the structure.

to_data1d

to_data1d(*, dI=None)

Return the curve as a fit-ready sasdata Data1D.

The curve is theory, so it carries no dQ and, unless dI is given, no dI. It carries qmin, qmax and an empty mask, which fit engines such as IQuana's expect. Fitting it then needs an explicit weighting and no resolution smearing.

sasdata is an optional dependency (pip install "sinccity[sasdata]").

Parameters:

Name	Type	Description	Default
dI		Optional uncertainties: finite, non-negative, one per q.	None

save_csv

save_csv(path) -> None

Write q and I(q) as CSV, with the settings in an ASCII header.

describe

describe() -> None

Print how the profile was computed.

plot

plot(*, data=None, log_scale: bool = True, show: bool | None = None)

Plot I(q); see sinccity.plotting.plot_profile.

sinccity.set_verbosity

set_verbosity(level: int | str = 'info') -> None

Set how much the calculator reports about what it is doing.

Parameters:

Name	Type	Description	Default
level	int | str	'quiet' to drop the progress messages and keep only warnings, or any standard logging level as a name ('info', 'debug', 'warning', 'error') or as an integer. Pass logging.CRITICAL to suppress the warnings as well.	'info'

Raises:

Type	Description
ValueError	If level is not a recognized level name.