# state.m

Generates Hilbert space density matrices and Liouville space state vectors from their human-readable descriptions.

## Syntax

    rho=state(spin_system,states,spins,state_type,method)


## Arguments

The function supports three types of calls:

1. If a state is given as a character string and spins are named by passing a character string, e.g.

    sum_Lz=state(spin_system,'Lz','13C');


the function returns the sum of the corresponding single-spin states on all spins with that name. In the example above, the sum of Lz states on all carbons in the system will be returned:

$\hat{\rho }=\hat{L}_{\text{Z}}^{\left( 1 \right)}+\hat{L}_{\text{Z}}^{\left( 2 \right)}+\hat{L}_{\text{Z}}^{\left( 3 \right)}+...$

Valid labels for states in this type of call are 'E', 'Lz', 'L+', 'L-' and 'Tl,m'. Valid labels for spins are standard isotope names as well as 'nuclei', 'electrons' and 'all'.

2. If one input is a string and the other is a vector, e.g.

    sum_Lz=operator(spin_system,'Lz',[1 2 4]);


the function returns the sum of all single-spin states for all spins with the specified numbers. In the example above, the sum of Lz states for spins 1, 2, and 4 will be returned. Valid labels for states in this type of call are 'E', 'Lz', 'L+', 'L-', and 'Tl,m'. In the latter case, l and m are integers.

3. If the states are supplied as a cell array of strings and spins as a cell array of numbers, a product state is produced, e.g.

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


will return the LzS+ product state with Lz on spin 1 and L+ on spin 2. In the example above, the function would return the following state:

$\hat{\rho }=\hat{L}_{\text{Z}}^{\left( 1 \right)}\otimes \hat{L}_{+}^{\left( 2 \right)}$

Valid labels for states in the cell array are 'E', 'Lz', 'L+', 'L-', 'Tl,m'.

The fourth argument provides a finer control over the generation of the state vector or state matrix. The following possibilities exist in sphten-liouv formalism:

    'cheap'  - the state vector is generated without
normalisation. For very large spin sys-
tens this is much faster

'exact'  - exact state vector with correct normalisation

'chem'   - the exact state vector weighted with the
concentrations specified in inter.chem.concs
field under chemical kinetics parameters


This option is ignored in Hilbert space.

## Outputs

    rho     - a Hilbert space density matrix or a Liouville
space state vector


## Examples

1. L+ state on spin 3

    rho=state(spin_system,{'L+'},{3});


An operator will be generated in Hilbert space and a state vector in Liouville space.

2. A sum of Lx states on all 15N spins in the system

    rho=(state(spin_system,'L+','15N')+state(spin_system,'L-','15N'))/2;


An operator will be generated in Hilbert space and a state vector in Liouville space.

3. AxBx state between spin 2 and spin 5

Both components are Cartesian and must therefore be translated into the convention above:

$\begin{matrix} {{{\hat{A}}}_{\text{X}}}=\frac{{{{\hat{A}}}_{+}}+{{{\hat{A}}}_{-}}}{2};\text{ }{{{\hat{B}}}_{\text{X}}}=\frac{{{{\hat{B}}}_{+}}+{{{\hat{B}}}_{-}}}{2} \\ {{{\hat{A}}}_{\text{X}}}{{{\hat{B}}}_{\text{X}}}=\frac{1}{4}\left( {{{\hat{A}}}_{\text{+}}}{{{\hat{B}}}_{+}}+{{{\hat{A}}}_{+}}{{{\hat{B}}}_{-}}+{{{\hat{A}}}_{-}}{{{\hat{B}}}_{+}}+{{{\hat{A}}}_{-}}{{{\hat{B}}}_{-}} \right) \\ \end{matrix}$

The Spinach code would therefore be:

    AxBx=(state(spin_system,{'L+','L+'},{2,5})+...
state(spin_system,{'L+','L-'},{2,5})+...
state(spin_system,{'L-','L+'},{2,5})+...
state(spin_system,{'L-','L-'},{2,5}))/4;


An operator will be generated in Hilbert space and a state vector in Liouville space.

## Notes

In situations where the norm of the requested state vector is inconsequential, the method parameter may be specified. Setting method to 'cheap' triggers a very fast state vector generation procedure with the caveat that the norm of the resulting state vector is not guaranteed to be consistent with other state vectors. This switch is only applicable to the spherical tensor basis set.