SingleChainStructureFactor¶

class mdcraft.analysis.polymer.SingleChainStructureFactor(groups: AtomGroup, groupings: str = 'atoms', n_chains: int = None, n_monomers: int = None, *, form: str = 'exp', dimensions: ndarray[float] | Quantity | Quantity = None, n_points: int = 32, n_surfaces: int = None, n_surface_points: int = 8, q_max: float | Quantity | Quantity = None, wavevectors: ndarray[float] = None, sort: bool = True, unique: bool = True, unwrap: bool = False, parallel: bool = False, verbose: bool = True, **kwargs)[source]¶

Bases: NumbaAnalysisBase, _PolymerAnalysisBase

Serial and parallel implementations to calculate the single-chain structure factor \(S_\mathrm{sc}(q)\) of a homopolymer.

It is defined as

\[S_{\mathrm{sc}}(q)=\frac{1}{MN}\left\langle \sum_{m=1}^M\sum_{j=1}^{N}\sum_{k=1}^{N}\exp{ [i\mathbf{q}\cdot(\mathbf{r}_j-\mathbf{r}_k)]}\right\rangle\]

where \(M\) is the number of chains, \(N\) is the chain length, \(\mathbf{q}\) and \(q\) are the scattering wavevector and its magnitude, respectively, and \(\mathbf{r}_i\) is the position of the \(i\)-th monomer.

The single-chain structure factor reveals information about the characteristic length scales of the polymer:

In the Guinier regime (\(qR_g\ll1\)), \(S_{\mathrm{sc}}(q)^{-1}\approx N(1-(qR_g)^2/3)\) can be used to determine the radius of gyration \(R_g\).
In the Porod regime (\(qR_g\gg1\)), \(S_{\mathrm{sc}}(q)=1\) since the only contribution is the self-scattering of the monomers.
In the intermediate regime, the slope \(s\) of the log-log plot of \(S_{\mathrm{sc}}(q)\) is related to the scaling exponent \(\nu\) via \(\nu=-1/s\).

Parameters:

groupsMDAnalysis.AtomGroup or array-like

Groups of polymers to be analyzed.

Note

All polymers in each group must have the same chain length.

groupingsstr or array-like, default: "atoms"

Determines whether the centers of mass are used in lieu of individual atom positions. If groupings is a str, the same value is used for all groups.

Note

In a standard trajectory file, segments (or chains) contain residues (or molecules), and residues contain atoms. This heirarchy must be adhered to for this analysis module to function correctly. If your trajectory file does not contain the correct residue or segment information, provide the number of chains and chain lengths in n_chains and n_monomers, respectively.

Valid values:

"atoms": Atom positions (generally or for coarse-grained simulations).
"residues": Residues’ centers of mass (for atomistic simulations).

n_chainsint or array-like, optional

Number of chains \(M\) in each polymer group. Must be provided if the trajectory does not adhere to the standard container heirarchy. If an int is provided, the same value is used for all groups.

Shape: \((N_\mathrm{groups},)\).

n_monomersint or array-like, optional

Number of monomers \(N\) in each chain in each polymer group. Must be provided if the trajectory does not adhere to the standard container heirarchy. If an int is provided, the same value is used for all groups.

Shape: \((N_\mathrm{groups},)\).

formstr, keyword-only, default: "exp"

Expression used to evaluate the single-chain structure factors.

Valid values:

"exp": Exponential form. Slightly faster due to fewer mathematical operations.
"trig": Trigonometric form. Slightly slower but doesn’t have overflow issues.

dimensionsarray-like, openmm.unit.Quantity, or pint.Quantity, keyword-only, optional

System dimensions \((L_x,\,L_y,\,L_z)\). Only used to determine the scattering wavevectors when wavevectors is not specified.

Shape: \((3,)\).

Reference unit: \(\mathrm{Å}\).

n_pointsint, keyword-only, default: 32

Number of points \(n_\mathrm{points}\) in the scattering wavevector grid to generate

\[\mathbf{q}=2\pi\left(\frac{a}{L_x},\,\frac{b}{L_y},\, \frac{c}{L_z}\right)\]

where \(a\), \(b\), and \(c\) are integers from \(0\) up to \(n_\mathrm{points}-1\).

Additional wavevectors can be introduced via n_surfaces and n_surface_points for more accurate structure factors at small wavenumbers. Alternatively, the desired wavevectors can be specified directly in wavevectors.

n_surfacesint, keyword-only, optional

Number of spherical surfaces in the first octant that intersect with the grid wavevectors along the three coordinate axes for which to introduce extra wavevectors for more accurate structure factor values. Only available if the system is perfectly cubic.

n_surface_pointsint, keyword-only, default: 8

Number of extra wavevectors to introduce per spherical surface. Has no effect if n_surfaces is not specified.

q_maxfloat, openmm.unit.Quantity, or pint.Quantity, keyword-only, optional

Maximum wavenumber \(q_\mathrm{max}\).

Reference unit: \(\mathrm{Å}^{-1}\).

wavevectorsarray-like, openmm.unit.Quantity, or pint.Quantity, keyword-only, optional

Scattering wavevectors for which to compute structure factors. Has precedence over n_points, n_surfaces, and n_surface_points if specified.

Shape: \((N_q,\,3)\).

Reference unit: \(\mathrm{Å}^{-1}\).

sortbool, keyword-only, default: True

Determines whether the results are sorted by the wavenumbers.

uniquebool, keyword-only, default: True

Determines whether structure factors for the same wavenumber are grouped and averaged.

parallelbool, keyword-only, default: False

Determines whether the analysis is performed in parallel.

verbosebool, keyword-only, default: True

Determines whether detailed progress is shown.

**kwargs

Additional keyword arguments to pass to MDAnalysis.analysis.base.AnalysisBase.

Attributes:

universeMDAnalysis.Universe

MDAnalysis.core.universe.Universe object containing all information describing the system.

results.unitsdict

Reference units for the results. For example, to get the reference units for results.wavenumbers, call results.units["wavenumbers"].

results.wavenumbersnumpy.ndarray

Wavenumbers \(q\).

Shape: \((N_q,)\).

Reference unit: \(\mathrm{Å}^{-1}\).

results.scsfnumpy.ndarray

Single-chain structure factors \(S_\mathrm{sc}(q)\).

Shape: \((N_q,)\).

Methods

`run`	Performs the calculation.
`save`	Saves results to a binary or archive file in NumPy format.

run(start: int = None, stop: int = None, step: int = None, frames: slice | ndarray[int] = None, verbose: bool = None, *, n_threads: int = None, **kwargs) → NumbaAnalysisBase¶

Performs the calculation.

Parameters:

startint, optional: Starting frame for analysis.
stopint, optional: Ending frame for analysis.
stepint, optional: Number of frames to skip between each analyzed frame.
framesslice or array-like, optional: Index or logical array of the desired trajectory frames.
verbosebool, optional: Determines whether detailed progress is shown.
n_threadsint, keyword-only, optional: Number of threads to use for analysis.
**kwargs: Additional keyword arguments to pass to MDAnalysis.lib.log.ProgressBar.

Returns:

selfNumbaAnalysisBase: Analysis object with results.

save(file: str | TextIO, archive: bool = True, compress: bool = True, **kwargs) → None¶

Saves results to a binary or archive file in NumPy format.

Parameters:

filestr or file: Filename or file-like object where the data will be saved. If file is a str, the .npy or .npz extension will be appended automatically if not already present.
archivebool, default: True: Determines whether the results are saved to a single archive file. If True, the data is stored in a .npz file. Otherwise, the data is saved to multiple .npy files.
compressbool, default: True: Determines whether the .npz file is compressed. Has no effect when archive=False.
**kwargs: Additional keyword arguments to pass to numpy.save(), numpy.savez(), or numpy.savez_compressed(), depending on the values of archive and compress.