schrodinger.application.jaguar.spin_simulator_v2 module¶

This simulation follows the simulation algorithm used in the Spinach package, which can be found here: https://github.com/IlyaKuprov/Spinach

It performs a numerical time propagation (in Liouville space) of the density matrix using a “Taylor expansion with scaling and squaring” scheme

Features:

Efficient Basis Set Indexing and Operator Representations (based
on irreducible spherical tensor operators)
Different Basis Truncation Strategies:
- Interaction Topology Analysis
- Conservation Law Screening
- Zero Track Elimination
- Path Tracing Elimination
- Destination State Screening

Main References:

[1] Book by Kuprov: “Spin: From Basic Symmetries to Quantum Optimal Control”: Springer Nature, 2023 https://doi.org/10.1007/978-3-031-05607-9
[2] Journal of Magnetic Resonance 208 (2011) 179–194: https://doi.org/10.1016/j.jmr.2010.11.008

Additional References:

[3] Journal of Magnetic Resonance 189 (2007) 241–250 [4] Journal of Magnetic Resonance 195 (2008) 45–51 [5] The Journal of Chemical Physics 132, 174101 2010

class schrodinger.application.jaguar.spin_simulator_v2.Parameters(offset: float, sweep: float, spectrum_type: str, axis_units: str = 'ppm', invert_axis: bool = True, max_subgraph_size: int = 14, timestep_npoints: int = 8192, spectrum_npoints: int = 16536)¶

Bases: object

offset: float¶

sweep: float¶

spectrum_type: str¶

axis_units: str = 'ppm'¶

invert_axis: bool = True¶

max_subgraph_size: int = 14¶

timestep_npoints: int = 8192¶

spectrum_npoints: int = 16536¶

__init__(offset: float, sweep: float, spectrum_type: str, axis_units: str = 'ppm', invert_axis: bool = True, max_subgraph_size: int = 14, timestep_npoints: int = 8192, spectrum_npoints: int = 16536) → None¶

schrodinger.application.jaguar.spin_simulator_v2.apodization(fid: ndarray[Any, dtype[ScalarType]]) → ndarray[Any, dtype[ScalarType]]¶

Post-processing cleanup of FID to remove unwanted ringing near peaks. Conventionally applied to NMR signals before FT. Typically NMR signals are truncated for time and signal/noise constraints. This trunctation introduces artifacts which are removed by a window function.

In this case an exponential window is used.

Parameters:: fid – input FID signal.
Returns:: FID signal apodized with exponential window.

class schrodinger.application.jaguar.spin_simulator_v2.SpinSystem(chemical_shifts: list[float], couplings: list[tuple[int, int, float]], magnet: float, isotopes: list[str], spectrum_type: str, xmin: float, xmax: float, timestep_npoints: int = 8192, spectrum_npoints: int = 16536, sym_groups: list[str] | None = None, sym_spins: list[list[int]] | None = None, max_subgraph_size: int = 14, debug: bool = False, debug_filename: str = 'debug')¶

Bases: object

Core Driver class for the simulation.

LIOUV_ZERO = 1e-07¶

PROP_ZERO = 1e-08¶

PROP_CHOP = 1e-10¶

KRYLOV_SWITCHOVER = 50000¶

ZTE_TOL = 1e-30¶

ZTE_NSTEPS = 10¶

ZTE_MAXDEN = 0.5¶

INTER_CUTOFF = 1e-05¶

PATH_TRACE = 1e-07¶

PATH_DROP = 1e-30¶

IRREP_DROP = 1e-30¶

SMALL_MATRIX = 200¶

DENSE_MATRIX = 0.25¶

__init__(chemical_shifts: list[float], couplings: list[tuple[int, int, float]], magnet: float, isotopes: list[str], spectrum_type: str, xmin: float, xmax: float, timestep_npoints: int = 8192, spectrum_npoints: int = 16536, sym_groups: list[str] | None = None, sym_spins: list[list[int]] | None = None, max_subgraph_size: int = 14, debug: bool = False, debug_filename: str = 'debug')¶

Parameter and option preprocessing.

Symmetry information is currently unused as the build-and-prune strategy currently implmented requires too much memory to be practical. Instead a constructive scheme should be developed, if it becomes apparent that symmetry optimizations are required.

simulate_spectrum(plot=False) → tuple[numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]], numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]]¶

Driver function to compute the NMR spectrum of this spin system.

Parameters:: plot – If True then a plot of the spectrum will be produced. Primarily for debugging purposes.
Returns:: Spectrum X (delta in ppm) and Y (signal) arrays.

pulse_acquire() → ndarray[Any, dtype[ScalarType]]¶

The standard 90-acquire pulse sequence.

Returns:: fid, numpy array containing the time propagated signal.

operator(operators: list[str] | str, spins: list[int] | str) → csr_array¶

Generates commutation superoperators from their user-friendly descriptions.

Example: LzSp = spin_system.operator([‘Lz’, ‘L+’], [1, 2]) This would return the [LzS+, ] commutation superoperator with Lz on spin 1 and L+ on spin 2.

Example: Sum_Lz = spin_system.operator(‘Lz’, ‘13C’) This would return the sum of [Lz, ] commutation superoperators on all carbons in the system.

Parameters:

operators – a list of strings. Each string may be ‘E’ (identity operator), ‘Lz’, ‘L+’, ‘L-’ or ‘Tl,m’ (higher spin orders as irreducible spherical tensors; l and m are both integers).
spins –
EITHER a list of integers specifying the numbers of spins on which the operators given in the ‘operators’ argument operate (this produces the corresponding multi-spin superoperator)

OR an isotope specification: ‘13C’, ‘15N’, ‘all’ (this produces a sum of single-spin operators on all the spins of the specified isotope).

Returns:

The operator sparse matrix.

human2opspec(operators: list[str], spins: list[int]) → tuple[list[int], float]¶

Converts user-friendly descriptions of spin states and operators into the formal description (opspec) used by Spinach kernel.

Example: opspec, coefficient = spin_system.human2opspec([‘Lz’, ‘L+’], [1, 2]) This would return the required opspec and coefficient to generate an LzL+ operator or state vector with Lz on the spins 1 and L+ on spin 2.

Parameters:

operators – a list of strings. Each string can be ‘E’ (identity operator), ‘Lz’, ‘L+’, ‘L-’ (single spin orders) or ‘Tl,m’ (higher spin orders as irreducible spherical tensors; l and m are both integers).
spins – a list of integers specifying the numbers of spins on which the operators given in the ‘operators’ argument operate.

Returns:

operator specification and coefficient

c_superop(opspec: list[int]) → csr_array¶

Computes commutation superoperators.

Parameters:: opspec – Operator specification
Returns:: Sparse matrix representation of operator.

p_superop(opspec: list[int], side: str, filter_commuting: bool = False) → csr_array¶

Returns superoperators corresponding to right or left multiplication of a density matrix by a user-specified operator. If specified, it uses commuting-path filtering, matching Spinach’s superop.m optimization which removes paths where source or destination sums to zero.

Parameters:

opspec – operator specification.
side – ‘left’ or ‘right’.
filter_commuting – Whether to enable commuting-path filtering, where paths with zero source or destination sums are removed before the main loop (matching Spinach’s superop.m).

Returns:

sparse matrix representation of super-operator

ist_product_table(mult: int) → tuple[list[scipy.sparse._csr.csr_array], list[scipy.sparse._csr.csr_array]]¶

Multiplication tables for irreducible spherical tensors.

Parameters:: mult – multiplicity
Returns:: Left and right product tensors

irr_sph_ten(mult: int, k: int | None = None) → list[scipy.sparse._coo.coo_array]¶

Returns an array of single-spin irreducible spherical tensor operators T(k,m).

Parameters:

mult – multiplicity
k – tensor rank

Returns:

List if spherical tensor operators

offset_superop() → ndarray[Any, dtype[ScalarType]]¶

Generates the offset superoperator.

When added to the main Liouvillian, the offset superoperator shifts the master frame of a given set of spins by a given amount (in Hz).

Parameters:

spins – May be set to ‘all’, ‘1H’, ‘13C’ etc.
offset_value – Offset value in Hz.

Returns:

Offset superoperator.

h_superop() → csr_array¶

Hamiltonian superoperator and its rotational decomposition for Liouville space simulations.

Returns:: H superoperator.

r_superop() → csr_array¶

The relaxation superoperator. Computes the Redfield superoperator by numerical evaluation of the integral in the Bloch-Redfield-Wangsness master equation in Liouville space.

WE ARE NOT USING THIS IN OUR SIMPLE NMR. Kept as placeholder for future development and parity with spinach.

Returns:: Redfield superoperator array, presently all zeros.

k_superop() → csr_array¶

Chemical kinetics superoperator.

WE ARE NOT USING THIS IN OUR SIMPLE NMR Kept as placeholder for future development and parity with spinach.

Returns:: Chemical kinetics superoperator array, presently all zeros.

state(states: list[str], spins: list[int] | str) → lil_array¶

Generates state vectors from their user-friendly descriptions.

Example:

LzSp=state(spin_system,{‘Lz’,’L+’},{1,2});

would return the LzS+ state with Lz on spin 1 and L+ on spin 2.

Example:

Sum_Lz=state(spin_system,’Lz’,’13C’);

would return the sum of Lz states on all carbons in the system.

Parameters:

states – Each string may be ‘E’ (identity state), ‘Lz’, ‘L+’, ‘L-’ or ‘Tl,m’ (higher spin states as irreducible spherical tensors; l and m are both integers).
spins – EITHER a list of integers specifying the numbers of spins to be generated in states given in the ‘states’ argument (this produces the corresponding multi-spin state) OR an isotope specification: ‘13C’, ‘15N’, ‘all’ (this produces a sum of single-spin states on all the spins of the specified isotope).

Returns:

State vectors.

statevec(opspec: list[int]) → lil_array¶

User-specified state vector. Converts a Spinach operator specification into a Liouville space state vector.

If the requested state is not in the basis, a ValueError is raised.

Parameters:: opspec – Operator specification constructed by human2opspec.
Returns:: The resulting state vector

equilibrium()¶

Thermal equilibrium state.

If the temperature is set to zero during initialization, returns the high-field, high-temperature approximation to the thermal equilibrium state. If the temperature is specified, returns the thermal equilibrium state of the Zeeman Hamiltonian, ignoring all couplings and offsets.

If the requested state is not in the basis, a ValueError is raised.

step(L: spmatrix, rho: spmatrix, time_step: float)¶

Propagation step function. Computes the action of a matrix exponential on a state vector without computing the exponential itself, using a reordered Taylor series with sub-stepping for monotonic convergence.

This matches the approach in Spinach’s step.m, which found the reordered Taylor process consistently superior to Krylov methods.

Reference: Chapter 4.9.6 of “Spin: From Basic Symmetries to Quantum Optimal Control” Book

Parameters:

L – The Liouvillian to be used for propagation.
rho – The state vector (or a horizontal stack thereof) to be propagated.
time_step – The length of the time step to take.

Returns:

The stepped state vector.

evolution(L: csr_array, coil: lil_array, rho: spmatrix, timestep: float, nsteps: int) → ndarray[Any, dtype[ScalarType]]¶

Time evolution function. Performs all types of time propagation with automatic trajectory level state space restriction.

Parameters:

L – the Liouvillian to be used during evolution
rho – the initial state vector or a horizontal stack thereof
coil – the detection state, used when ‘observable’ is specified as the output option
timestep – the length of each time step
nsteps – number of steps in the evolution

Returns:

the resulting state, observable, or trajectory based on the specified output

propagator(L: csr_array, timestep: float) → csr_array¶

Calculates the exponential propagator of L.

Parameters:

L – the Liouvillian matrix to propagate.
timestep – time step value (dt)

Return P:

The propagator matrix.

reduce(L: csr_array, rho: lil_array) → list[scipy.sparse._csr.csr_array]¶

Symmetry and trajectory-level state space restriction for a user-specified Liouvillian L and initial state rho. Applies all reduction methods and returns a list of projectors into a set of independent reduced subspaces. The projectors are to be used as follows:

L = P.T @ L @ P rho = P.T @ rho

Parameters:

L – Liouvillian matrix.
rho – Initial state vector.

Returns:

List of projector matrices.

zte(L: csr_array, rho: lil_array) → csr_array¶

Zero track elimination function. Inspects the first few steps in the system trajectory and drops the states that did not get populated to a user-specified tolerance.

Reference: Chapter 7.3.3 of “Spin: From Basic Symmetries to Quantum Optimal Control” Book

Parameters:

L – The Liouvillian to be used for time propagation
rho – The initial state to be used for time propagation

Returns:

projector matrix into the reduced space, to be used as follows: L = P.T @ L @ P, rho = P.T @ rho

path_trace(L: spmatrix) → list[scipy.sparse._csr.csr_array]¶

Liouvillian path tracing. Treats the given Liouvillian as the adjacency matrix of a graph, computes the weakly connected subgraphs of that graph, and returns a list of projectors into the corresponding independently evolving subspaces.

Reference: Chapter 7.3.5 of “Spin: From Basic Symmetries to Quantum Optimal Control” Book

Parameters:: L – User-supplied Liouvillian
Returns:: List of projectors into the independently evolving subspaces.

normest(A: sparray) → float¶

Cheap norm estimate for sparse matrix A.

Uses the 1-norm (maximum absolute column sum), which is O(nnz) for sparse matrices. This matches Spinach’s cheap_norm.m, which explicitly uses the cheapest available norm to avoid expensive SVD computation.

Parameters:: A – Sparse matrix to estimate the norm of.
Returns:: Estimated norm of matrix A.

clean_up(A: spmatrix, nonzero_tol: float) → spmatrix¶

Sparse matrix clean-up utility.

Parameters:

A – The matrix to clean up.
nonzero_tol – Tolerance below which values will be set to zero.

Returns:

A cleaned-up version of the input matrix.

plot_1d(spectrum, molname: str = 'TEST', runtime: float | None = None, data_only=False) → tuple[numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]], numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]]¶

Simple plotting function for debugging purposes. Builds the axes from spin information.

Parameters:

spectrum – spectrum data returned by running the simulation.
molname – Label to annotate the spectrum with.
runtime – The time taken to run the simulation, if present this will be annotated on the plot.
data_only – flag that only the x, y data should be returned, no plot should be made

Returns:

The x and y data that make up the plot.

plot_subgraphs(subgraphs: numpy.ndarray[Any, numpy.dtype[numpy._typing._generic_alias.ScalarType]] | None = None, fname: str = '')¶

Debugging function plotting the subgraph topology of the spin system.

Parameters:

subgraphs – Numpy array of boolean vectors flagging which spins are involved.
fname – filename that the figure should be written to. If empty the figure will show interactively instead.