Structures

sinccity.Structure dataclass

Point scatterers: atoms, lattice pixels or mesh-cell centroids.

Arrays are read-only copies owned by the structure. That protects against accidental mutation; it is not a guarantee (setflags can undo it).

Attributes:

Name	Type	Description
kind	str	'atoms', 'pixels' or 'cells'.
xyz	ndarray	Positions, shape (N, 3), Å.
sld	ndarray	Nuclear scattering length density per point, Å⁻², as the files store it (the calculator's sld_solvent is in 10⁻⁶ Å⁻²).
volume	ndarray	Volume per point, ų, all positive.
symbols	ndarray | None	Element symbols, atoms only.
bonds	ndarray | None	Index pairs from PDB CONECT records, atoms only.
cell_diameter	ndarray | None	Largest vertex-to-vertex distance per cell, cells only.
lattice	Lattice | None	The lattice the points sit on, pixels only.
resids,	(resnames, names)	Residue number, residue name and atom name per atom, from PDB and GRO files; None otherwise.
element_sources	dict[str, str]	Where the elements of each residue name came from: 'masses', 'elements', 'pdb', 'names' (guessed) or 'given' (from_atoms). Empty without residue names.
box	tuple[float, float, float] | None	The rectangular periodic box the file declared, Å; None when it declared none, a placeholder or a triclinic one.
reader_options	dict[str, Any] | None	The options the reader was called with, every key filled, so the file plus this dict rebuilds the structure. None for structures no reader made.
source	str	Absolute path of the file, or 'in-memory'.
source_sha256	str | None	Hash of the file as read.
format	str	'pdb', 'gro', 'sld', 'vtk' or 'arrays'.
notes	tuple[str, ...]	What the reader dropped, approximated or assumed.

total_volume property

total_volume: float

Sum of all point volumes, ų (V_all).

centre property

centre: ndarray

The middle of the bounding box, Å, as SasView's transform_center takes it.

masses property

masses: ndarray

Atomic masses in g/mol (atoms only).

from_arrays classmethod

from_arrays(xyz, sld, volume, *, symbols=None, bonds=None) -> Structure

Build a structure from arrays: positions (Å), SLD (Å⁻²) and volumes (ų).

Points with element symbols are atoms; otherwise they are pixels, and the lattice they sit on, if any, is detected.

from_atoms classmethod

from_atoms(xyz, symbols, *, resids=None, resnames=None, names=None, bonds=None) -> Structure

Build atoms whose SLD and volume come from their elements, as the readers do.

This is how atoms read by another program come in without a file. Positions in Å.

deuterated

deuterated(residues) -> Structure

A copy in which the hydrogens of these residue names have the SLD of D.

Volumes are unchanged: D and H have the same natural atomic volume. The copy keeps the source, but no reader made it, so its reader_options are None.

Raises:

Type	Description
StructureError	If the structure has no residue names, or a name is not in it or has no hydrogens.

with_symbols

with_symbols(symbols) -> Structure

A copy with corrected elements, and SLD and volumes recomputed from them.

The residue names whose elements change are recorded as 'elements' in element_sources. The copy keeps the source, but no reader made it, so its reader_options are None.

radius_of_gyration

radius_of_gyration(weights: str = 'sld', *, sld_solvent: float = 0.0) -> RgResult

Radius of gyration, as a diagnostic that never raises.

Parameters:

Name	Type	Description	Default
weights	str	'sld' weights each point by its contrast times volume (for atoms in vacuum, the scattering length); 'mass' uses atomic masses and the centre of mass (atoms only).	'sld'
sld_solvent	float	Solvent SLD in 10⁻⁶ Å⁻², for 'sld' weights.	0.0

summary

summary() -> dict[str, Any]

The facts describe() prints, as a plain dict.

describe

describe() -> None

Print a summary of the structure.

plot_points

plot_points(**kwargs: Any)

Draw the points in 3D; see sinccity.plotting.plot_points.

sinccity.RgResult dataclass

A radius of gyration, or the reason there is none.

sinccity.StructureError

Bases: ValueError

A structure file or array set cannot be used for a calculation.