schrodinger.application.jaguar.spin_simulator_v2 module

This simulation follows the simulation algorithm used in the Spinach package, which can be found here: https://doi.org/10.1016/j.jmr.2010.11.008

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.get_spectral_params(spectrum_spin: str, isotopes: List[str], shifts: numpy.ndarray, magnet: float) → Tuple[float, float]

Determine sweep and offset (in Hz) for the particular system under consideration.

Parameters

  • spectrum_spin – isotope that 1D NMR is probing, e.g. 1H

  • isotopes – list of isotopes for each spin in the system

  • shifts – list of chemical shifts in ppm for each spin in the system

  • magnet – strength of NMR magnet in Tesla

Returns

width and offset of spectral window

schrodinger.application.jaguar.spin_simulator_v2.apodization(fid: numpy.ndarray) → numpy.ndarray

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, timestep_npoints: int = 8192, spectrum_npoints: int = 16536, sym_groups: Optional[List[str]] = None, sym_spins: Optional[List[List[int]]] = None, max_subgraph_size: Optional[int] = 14, debug: bool = False, debug_filename: str = 'debug')

Bases: object

Core Driver class for the simulation.

SPEC_BUFFER = 0.9
LIOUV_ZERO = 1e-07
PROP_ZERO = 1e-08
PROP_NORM = 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, timestep_npoints: int = 8192, spectrum_npoints: int = 16536, sym_groups: Optional[List[str]] = None, sym_spins: Optional[List[List[int]]] = None, max_subgraph_size: Optional[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, numpy.ndarray]

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() → numpy.ndarray

The standard 90-acqure pulse sequence.

Returns

fid, numpy array containing the time propagated signal.

operator(operators: Union[List[str], str], spins: Union[List[int], str]) → scipy.sparse._arrays.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]) → scipy.sparse._arrays.csr_array

Computes commutation superoperators.

Parameters

opspec – Operator specification

Returns

Sparse matrix representation of operator.

p_superop(opspec: List[int], side: str) → scipy.sparse._arrays.csr_array

Returns superoperators corresponding to right or left multiplication of a density matrix by a user-specified operator.

Parameters

  • opspec – operator specification.

  • side – ‘left’ or ‘right’

Returns

sparse matrix representation of super-operator

ist_product_table(mult: int) → Tuple[List[scipy.sparse._arrays.csr_array], List[scipy.sparse._arrays.csr_array]]

Multiplication tables for irreducible spherical tensors.

Parameters

mult – multiplicity

Returns

Left and right product tensors

irr_sph_ten(mult: int, k: Optional[int] = None) → List[scipy.sparse._arrays.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() → numpy.ndarray

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() → scipy.sparse._arrays.csr_array

Hamiltonian superoperator and its rotational decomposition for Liouville space simulations.

Returns

H superoperator.

r_superop() → scipy.sparse._arrays.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() → scipy.sparse._arrays.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: Union[List[int], str]) → scipy.sparse._arrays.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]) → scipy.sparse._arrays.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: scipy.sparse._base.spmatrix, rho: scipy.sparse._base.spmatrix, time_step: float)

A propagation step function using Krylov propagation for large matrices and scipy’s expm for small matrices.

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: scipy.sparse._arrays.csr_array, coil: scipy.sparse._arrays.lil_array, rho: scipy.sparse._base.spmatrix, timestep: float, nsteps: int) → numpy.ndarray

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: scipy.sparse._arrays.csr_array, timestep: float) → scipy.sparse._arrays.csr_array

Calculates exponential propagators and propagator derivatives.

Parameters

  • L – the Liouvillian matrix to propagate.

  • timestep – time step value (dt)

Return P

The propagator matrix.

reduce(L: scipy.sparse._arrays.csr_array, rho: scipy.sparse._arrays.lil_array) → List[scipy.sparse._arrays.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: scipy.sparse._arrays.csr_array, rho: scipy.sparse._arrays.lil_array) → scipy.sparse._arrays.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.

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: scipy.sparse._base.spmatrix) → List[scipy.sparse._arrays.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.

Parameters

L – User-supplied Liouvillian

Returns

List of projectors into the independently evolving subspaces.

normest(A: scipy.sparse._base.spmatrix) → float

Estimate the norm of sparse matrix A.

Currently wraps scipy.sparse.linalg.norm as a placeholder for an optimized norm estimation.

Parameters

A – Sparse matrix to estimate the norm of.

Returns

Estimated norm of matrix A.

clean_up(A: scipy.sparse._base.spmatrix, nonzero_tol: float) → scipy.sparse._base.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: Optional[float] = None, data_only=False) → Tuple[numpy.ndarray, numpy.ndarray]

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: Optional[numpy.ndarray] = 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.