hqs_nmr.solver.implementations.system_tools

A collection of functions related to constructing the system.

This module also includes functions taking care of the bookkeeping of all the quantum numbers and indices when the local SU2 symmetries should be taken into account.

Functions

`S2_term_combined_higher_spins`(j_total, j_list)	Calculates the expectation value to the operator S_total^2 - S_1^2 - S_2^2.
`S2_term_higher_spin`(spin[, S2_term])	Calculates the expectation value to the operator sum J S_i S_j.
`S2_term_spin_half`(j_total, number_spin_half)	Calculates the expectation value to the operator S_total^2 - S_1^2 - S_2^2.
`combine_n_subgroups`(list_subgroups, J_inter)	Take all higher spin states for multiple subgroups and combine them in all combinations.
`combine_two_spins`(spin1, spin2, J_coupling)	Combines two higher spins states to create a list of new higher spin states.
`combine_two_subgroups`(subgroup1, subgroup2, ...)	Take all higher spin states for two subgroups and combine them in all combinations.
`get_J_sectors`(M)	Get the different S^2 sectors when combining multiple spins with equal S^2 quantum numbers.
`get_operator_list`(num_spins, gyromagnetic_ratios)	Get list of site-resolved operators.
`get_operator_sum`(num_spins, gyromagnetic_ratios)	Get sum of operators.
`get_symmetrized_matrices`(J_coupling, Jz, ...)	Reorder and simplify J_coupling and Jz according to grouplist.
`identify_symmetry_groups`(J_coupling, Jz[, ...])	Identify groups of spins, that couple in the same way to the rest of the system.
`split_group`(J_coupling, group_indices)	Split groups consisting of multiple symmetric subgroups into subgroups.

Classes

`EffectiveSpinSystem`(solver_settings, ...)	Class that defines an effective spin system.
`Group`(subgroup_list, effective_spin_system)	Class to store all information on one group.
`HigherSpinState`(J, J_coupling[, ...])	Class to store information associated with a higher spin state.

class hqs_nmr.solver.implementations.system_tools.EffectiveSpinSystem(solver_settings: NMRSolverSettings, J_coupling: np.ndarray, Jz: np.ndarray)

Class that defines an effective spin system.

An effective spin system is a representation of a NMR Hamiltonian, in which information on symmetry groups can be stored. We define a symmetry group as a set of spins that couple symmetrically to the rest of the system. These can be represented as one spin of a higher order spin representation allowing us to exploit local SU2 symmetry. This leads to a reduced representation of the J-coupling matrix and the magnetic field terms.

Note: In order to exploit local SU2 symmetries hJz and hJp have to be the same matrices, hence we only save one matrix here called J_coupling.

Create effective spin system.

Parameters:

solver_settings – NMRSolverSettings object storing information on group finding.
J_coupling – Matrix with J-coupling terms.
Jz – Vector with Jz terms.

__init__(solver_settings: NMRSolverSettings, J_coupling: np.ndarray, Jz: np.ndarray) → None

Create effective spin system.

Parameters:

solver_settings – NMRSolverSettings object storing information on group finding.
J_coupling – Matrix with J-coupling terms.
Jz – Vector with Jz terms.

copy() → EffectiveSpinSystem

Create identical copy of the effective spin system.

Returns:: Copy of the effective spin system.

identify_effective_spin_contributions(spin_contributions: list[int]) → list[int]

Get effective spin contribution indices as stored in the effective spin system.

Parameters:: spin_contributions – Indices of the spins to analyze.
Returns:: List with effective spin contribution indices.

identify_effective_spin_index(spin_index: int) → int

Get effective spin index as stored in the effective spin system.

Parameters:: spin_index – Index for which to return the effective spin index.
Returns:: Effective spin index.

num_spin_half(spin_index: int) → int

Return number of spin half a spin is made up from.

The spin is identified by its index in the non-reduced ordering of the spin indices.

Parameters:

spin_index – Index of the spin to analyze. Spin index has to be taken from original
ordering.

Returns:

Number of spin half that make up a spin.

set_groups(group_list: list[NDArray[numpy_int]]) → None

Set the groups in the effective spin system.

This function also automatically creates a reduced version of the J coupling matrix as well as the Jz terms, where the groups are represented by a single site of higher spin representation and are ordered to the end of the system.

Parameters:: group_list – List of lists with the indices of the individual groups in the effective spin system.

class hqs_nmr.solver.implementations.system_tools.Group(subgroup_list: list[NDArray[numpy_int]], effective_spin_system: EffectiveSpinSystem)

Class to store all information on one group.

Create object representing on group.

Parameters:

subgroup_list – List with lists of subgroup indices.
effective_spin_system – Effective spin system the group is in.

__init__(subgroup_list: list[NDArray[numpy_int]], effective_spin_system: EffectiveSpinSystem) → None

Create object representing on group.

Parameters:

subgroup_list – List with lists of subgroup indices.
effective_spin_system – Effective spin system the group is in.

class hqs_nmr.solver.implementations.system_tools.HigherSpinState(J: float, J_coupling: float, list_higher_spins: list[HigherSpinState] | None = None, number_spin_half: int | None = None)

Class to store information associated with a higher spin state.

Each spin state consists of an overall quantum number J, the J_coupling value describing the coupling of the subparts of the spin and either a list of higher spins states the spin state is made up of (typically just two spins) or the number of spin half that make up the higher spin.

Create HigherSpinState.

Parameters:

J – J quantum number.
J_coupling – J coupling of the inner constituents of the spin.
list_higher_spins – List of higher spins states the spin state is created from. Defaults to None.
number_spin_half – Number of spin 1/2 the higher spin state is created from. Defaults to None.

__init__(J: float, J_coupling: float, list_higher_spins: list[HigherSpinState] | None = None, number_spin_half: int | None = None) → None

Create HigherSpinState.

Parameters:

J – J quantum number.
J_coupling – J coupling of the inner constituents of the spin.
list_higher_spins – List of higher spins states the spin state is created from. Defaults to None.
number_spin_half – Number of spin 1/2 the higher spin state is created from. Defaults to None.

info() → None: Prints all information of the spin state.

hqs_nmr.solver.implementations.system_tools.S2_term_combined_higher_spins(j_total: float, j_list: list[HigherSpinState]) → float

Calculates the expectation value to the operator S_total^2 - S_1^2 - S_2^2.

Applies to a vector in the basis | J, M, j_1, j_2 >.

Parameters:

j_total – Total spin.
j_list – List with spin representations of original sites.

Returns.:: Expectation value.

hqs_nmr.solver.implementations.system_tools.S2_term_higher_spin(spin: HigherSpinState, S2_term: float = 0) → float

Calculates the expectation value to the operator sum J S_i S_j.

Note that the expectation value only contains terms where the operator acts on symmetric groups.

Parameters:

spin – Higher spin state.
S2_term – Expectation value. Defaults to zero.

Returns.:: Expectation value.

hqs_nmr.solver.implementations.system_tools.S2_term_spin_half(j_total: float, number_spin_half: int | None) → float

Calculates the expectation value to the operator S_total^2 - S_1^2 - S_2^2.

Applies to a vector in the basis | J, M, j_1, j_2 >.

Parameters:

j_total – Total spin.
number_spin_half – Number of spin half the spin is created from.

Returns.:: Expectation value.

hqs_nmr.solver.implementations.system_tools.combine_n_subgroups(list_subgroups: list[list[HigherSpinState]], J_inter: list[float]) → list[HigherSpinState]

Take all higher spin states for multiple subgroups and combine them in all combinations.

Parameters:

list_subgroups – List with lists of all spin states in the subgroups.
J_inter – List of coupling constants of the subgroups.

Returns:

List of combined spin states.

hqs_nmr.solver.implementations.system_tools.combine_two_spins(spin1: HigherSpinState, spin2: HigherSpinState, J_coupling: float) → list[HigherSpinState]

Combines two higher spins states to create a list of new higher spin states.

Parameters:

spin1 – First higher spin state.
spin2 – Second higher spin state.
J_coupling – Coupling of the two spins

Returns:

List of combined higher spin states.

hqs_nmr.solver.implementations.system_tools.combine_two_subgroups(subgroup1: list[HigherSpinState], subgroup2: list[HigherSpinState], J_inter: float) → list[HigherSpinState]

Take all higher spin states for two subgroups and combine them in all combinations.

Parameters:

subgroup1 – List of all spin states in subgroup 1
subgroup2 – List of all spin states in subgroup 2
J_inter – Coupling constant of the two subgroups.

Returns:

List of combined spin states.

hqs_nmr.solver.implementations.system_tools.get_J_sectors(M: int) → list[float]

Get the different S^2 sectors when combining multiple spins with equal S^2 quantum numbers.

Parameters:: M – Number of sites.

hqs_nmr.solver.implementations.system_tools.get_operator_list(num_spins: int, gyromagnetic_ratios: ndarray) → list[ExpressionSpinful]

Get list of site-resolved operators.

Parameters:

num_spins – Total number of spins.
gyromagnetic_ratios – Array of the gyromagnetic factors per site.

Returns:

List with operators defined as fermion expressions.

hqs_nmr.solver.implementations.system_tools.get_operator_sum(num_spins: int, gyromagnetic_ratios: ndarray) → ExpressionSpinful

Get sum of operators.

Parameters:

num_spins – Total number of spins.
gyromagnetic_ratios – Array of the gyromagnetic factors per site.

Returns:

Sum of operators defined as fermion expressions.

hqs_nmr.solver.implementations.system_tools.get_symmetrized_matrices(J_coupling: np.ndarray, Jz: np.ndarray, grouplist: list[NDArray[numpy_int]]) → tuple[np.ndarray, np.ndarray, list[float], np.ndarray]

Reorder and simplify J_coupling and Jz according to grouplist.

Parameters:

J_coupling – Matrix with J couplings.
Jz – Matrix with magnetic fields.
grouplist – List of lists containing the indices of the individual groups.

Returns:

Reduced and reordered J_coupling, Jz and list with intra group couplings

hqs_nmr.solver.implementations.system_tools.identify_symmetry_groups(J_coupling: np.ndarray, Jz: np.ndarray, tolerance_shifts_percent: float = 1.0, tolerance_couplings_percent: float = 1.0, verbose: int = 0) → list[NDArray[numpy_int]]

Identify groups of spins, that couple in the same way to the rest of the system.

We first determine candidates for groups, by grouping spins with similar Jz values (meaning they differ by less then tolerance_shifts) together. Then we remove those spins from the candidate list, that are not strong coupling within the group. Finally we compare the coupling of the spins to the rest of the system using tolerance_couplings. Those that are coupling in the same way are assumed to be a group.

Parameters:

J_coupling – Matrix with the spin-spin coupling.
Jz – Vector with local fields coupling to S^z.
tolerance_shifts_percent – Tolerance in Jz values (in percent) that is allowed for spins to be grouped together. Defaults to 1.0.
tolerance_couplings_percent – Tolerance in J coupling values (in percent) that is allowed for spins to be grouped together. Defaults to 1.0.
verbose – Verbosity level of the calculation. Defaults to zero.

Returns:

A list of arrays containing the groups.

hqs_nmr.solver.implementations.system_tools.split_group(J_coupling: np.ndarray, group_indices: np.ndarray) → list[NDArray[numpy_int]]

Split groups consisting of multiple symmetric subgroups into subgroups.

Example: In propane the two methyl groups are identified as one group up to now, but we split them here.

Parameters:

J_coupling – Array with J coupling matrix.
group_indices – List with the indices of one group.

Returns:

List of lists, where the inner lists contain the indices of the subgroups.