mrsimulator

https://mrsimulator.readthedocs.io/en/stable
Admin
mrsimulator is a Python library for computing NMR spectra from spin system models using quantum...
Tokens:20,494
Snippets:128
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Create Site object examples

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/site.html

Demonstrates creating Site objects using dictionaries or SymmetricTensor objects.

```python
>>> site1 = Site(
...     isotope='33S',
...     isotropic_chemical_shift=20, # in ppm
...     shielding_symmetric={
...         "zeta": 10, # in ppm
...         "eta": 0.5
...     },
...     quadrupolar={
...         "Cq": 5.1e6, # in Hz
...         "eta": 0.5
...     }
... )
```

```python
>>> site1 = Site(
...     isotope='13C',
...     isotropic_chemical_shift=20, # in ppm
...     shielding_symmetric=SymmetricTensor(zeta=10, eta=0.5),
... )
```

--------------------------------

### Retrieve all transitions

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Get a list of all possible spin transitions in the system.

```python
>>> spin_system_1H_13C.all_transitions()  # 16 two energy level transitions
[|-0.5, -0.5⟩⟨-0.5, -0.5|,
|-0.5, 0.5⟩⟨-0.5, -0.5|,
|0.5, -0.5⟩⟨-0.5, -0.5|,
|0.5, 0.5⟩⟨-0.5, -0.5|,
|-0.5, -0.5⟩⟨-0.5, 0.5|,
|-0.5, 0.5⟩⟨-0.5, 0.5|,
|0.5, -0.5⟩⟨-0.5, 0.5|,
|0.5, 0.5⟩⟨-0.5, 0.5|,
|-0.5, -0.5⟩⟨0.5, -0.5|,
|-0.5, 0.5⟩⟨0.5, -0.5|,
|0.5, -0.5⟩⟨0.5, -0.5|,
|0.5, 0.5⟩⟨0.5, -0.5|,
|-0.5, -0.5⟩⟨0.5, 0.5|,
|-0.5, 0.5⟩⟨0.5, 0.5|,
|0.5, -0.5⟩⟨0.5, 0.5|,
|0.5, 0.5⟩⟨0.5, 0.5|]
```

--------------------------------

### GET /sites

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Retrieves a list of unique sites within the Simulator object.

```APIDOC
## GET /sites

### Description
Returns a list of unique Site objects contained within the Simulator object.

### Method
GET

### Response
#### Success Response (200)
- **sites** (list) - A Sites object containing the list of unique site objects.
```

--------------------------------

### Parse dictionary with units

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/site.html

Example of parsing a dictionary representation of a Site object.

```python
>>> site_dict = {
...    "isotope": "13C",
```

--------------------------------

### Utility Functions

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/utils.html

Provides access to utility functions for spectral simulation setup.

```APIDOC
## Utility Functions API

### Description
This section details the utility functions available for setting up spectral simulations.

### Functions

#### `single_site_system_generator()`

##### Description
Generates a single-site spin system.

##### Usage
```python
single_site_system_generator()
```

#### `site_generator()`

##### Description
Generates a spin site.

##### Usage
```python
site_generator()
```

#### `get_spectral_dimensions()`

##### Description
Retrieves the spectral dimensions for a simulation.

##### Usage
```python
get_spectral_dimensions()
```
```

--------------------------------

### Get All Isotopes from Simulator

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Retrieves a list of all unique isotopes present in the simulator's spin systems. Can optionally return only isotope symbols.

```python
>>> sim.get_isotopes()
[Isotope(symbol='13C'), Isotope(symbol='1H'), Isotope(symbol='27Al')]
>>> sim.get_isotopes(symbol=True)
['13C', '1H', '27Al']
```

--------------------------------

### Get Reduced Dictionary Representation

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator_config.html

Obtain a dictionary representation of the ConfigSimulator object, excluding specified keys and keys with None values. Useful for serialization or comparison.

```python
a.reduced_dict()
```

--------------------------------

### Initialize Simulator and Set Spin Systems

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Demonstrates initializing a Simulator object and assigning spin systems using both SpinSystem objects and equivalent dictionaries.

```python
>>> sim = Simulator()
>>> sim.spin_systems = [
...     SpinSystem(sites=[Site(isotope='17O')], abundance=0.015),
...     SpinSystem(sites=[Site(isotope='1H')], abundance=1),
... ]
```

```python
>>> # or equivalently
>>> sim.spin_systems = [
...     {'sites': [{'isotope': '17O'}], 'abundance': 0.015},
...     {'sites': [{'isotope': '1H'}], 'abundance': 1},
... ]
```

--------------------------------

### SpinSystem Class Initialization

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Demonstrates how to initialize a SpinSystem object with various optional parameters.

```APIDOC
## SpinSystem Class

### Description
Base class representing an isolated spin system containing multiple sites and couplings amongst them.

### Parameters
- **name** (str) - Optional - The name or ID of the spin system.
- **description** (str) - Optional - A description of the spin system.
- **label** (str) - Optional - A label for the spin system.
- **property_units** (Dict) - Optional - Dictionary for property units, defaults to {'abundance': 'pct'}.
- **sites** (Union[List[Site], ndarray]) - Optional - A list of Site or equivalent dict objects within the spin system.
- **couplings** (Union[List[Coupling], ndarray]) - Optional - A list of Coupling or equivalent dict objects within the spin system.
- **abundance** (ConstrainedFloatValue) - Optional - The abundance of the spin system in units of %. Defaults to 100.0.
- **transition_pathways** (List) - Optional - A list of TransitionPathway or equivalent dict objects.

### Request Example
```python
from mrsimulator import SpinSystem, Site, Coupling

sys1 = SpinSystem(name="1H-17O-0", description="A test for the spin system", label="Heteronuclear spin system", abundance=10.0)
sys1.sites = [Site(isotope="17O"), Site(isotope="1H")]
sys1.couplings = [
    Coupling(site_index=[0, 1], isotropic_j=10.1),
    Coupling(site_index=[2, 1], dipolar={"D": 1500})
]
```
```

--------------------------------

### Configure Simulator Settings

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Illustrates configuring the simulator using a ConfigSimulator object or an equivalent dictionary for parameters like sidebands, integration density, and decomposition.

```python
>>> from mrsimulator.simulator.config import ConfigSimulator
>>> sim.config = ConfigSimulator(
...     number_of_sidebands=32,
...     integration_density=64,
...     integration_volume='hemisphere',
...     decompose_spectrum='spin_system',
... )
```

```python
>>> # or equivalently
>>> sim.config = {
...     'number_of_sidebands': 32,
...     'integration_density': 64,
...     'integration_volume': 'hemisphere',
...     'decompose_spectrum': 'spin_system',
... }
```

--------------------------------

### Site Class Initialization and Attributes

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/site.html

Demonstrates how to initialize a Site object and set its various attributes, including isotope, chemical shift, and tensor parameters.

```APIDOC
## Site Class

### Description
Represents a single-site nuclear spin interaction tensor parameters. The single-site nuclear spin interaction tensors include the nuclear shielding and the electric quadrupolar tensor.

### Initialization Parameters
- **name** (str, optional) - The name or id of the site.
- **description** (str, optional) - A description of the site.
- **label** (str, optional) - The label for the site.
- **property_units** (Dict, optional) - Dictionary for property units, defaults to {'isotropic_chemical_shift': 'ppm'}.
- **isotope** (Union[str, dict, Isotope], optional) - Isotope information, defaults to '1H'.
- **isotropic_chemical_shift** (float, optional) - The isotropic chemical shift of the site in ppm, defaults to 0.0.
- **shielding_symmetric** (SymmetricTensor or dict, optional) - Parameters for the symmetric part of the nuclear shielding tensor.
- **shielding_antisymmetric** (AntisymmetricTensor or dict, optional) - Parameters for the antisymmetric part of the nuclear shielding tensor.
- **quadrupolar** (SymmetricTensor or dict, optional) - Parameters for the electric-field gradient tensor.

### Attribute Documentation

- **isotope** (str, optional) - A string expressed as an atomic number followed by an isotope symbol, eg., ‘13C’, ‘17O’. The default value is ‘1H’.
- **isotropic_chemical_shift** (float, optional) - The isotropic chemical shift of the site in ppm. The default value is 0.
- **shielding_symmetric** (SymmetricTensor or dict, optional) - The attribute represents the parameters of the irreducible second-rank traceless symmetric part of the nuclear shielding tensor. The default value is None.
- **shielding_antisymmetric** (AntisymmetricTensor or dict, optional) - The attribute represents the parameters of the irreducible first-rank antisymmetric part of the nuclear shielding tensor. The default value is None.
- **quadrupolar** (SymmetricTensor or dict, optional) - The attribute represents the parameters of the traceless irreducible second-rank symmetric part of the electric-field gradient tensor. The default value is None.
- **name** (str, optional) - The name or id of the site. The default value is None.
- **label** (str, optional) - The label for the site. The default value is None.
- **description** (str, optional) - A description of the site. The default value is None.

### Examples
```python
>>> from mrsimulator import Site
>>> from mrsimulator.tensor import SymmetricTensor, AntisymmetricTensor

>>> # Example 1: Site with default values
>>> site = Site()

>>> # Example 2: Site with specific isotope and chemical shift
>>> site = Site(isotope='2H', isotropic_chemical_shift=43.3)

>>> # Example 3: Site with symmetric shielding tensor
>>> site.shielding_symmetric = {'zeta': 10, 'eta': 0.5}
>>> # or equivalently
>>> site.shielding_symmetric = SymmetricTensor(zeta=10, eta=0.5)

>>> # Example 4: Site with antisymmetric shielding tensor
>>> site.shielding_antisymmetric = {'zeta': 20}
>>> # or equivalently
>>> site.shielding_antisymmetric = AntisymmetricTensor(zeta=20)

>>> # Example 5: Site with quadrupolar tensor
>>> site.quadrupolar = {'Cq': 3.2e6, 'eta': 0.52}
>>> # or equivalently
>>> site.quadrupolar = SymmetricTensor(Cq=3.2e6, eta=0.52)

>>> # Example 6: Site with name, label, and description
>>> site.name = '2H-0'
>>> site.label = 'Quad site'
>>> site.description = 'An example Quadrupolar site.'

>>> # Example 7: Complex site configuration
>>> site1 = Site(
...     isotope='33S',
...     isotropic_chemical_shift=20, # in ppm
...     shielding_symmetric={
...         "zeta": 10, # in ppm
...         "eta": 0.5
...     },
...     quadrupolar={
...         "Cq": 5.1e6, # in Hz
...         "eta": 0.5
...     }
... )

>>> # Example 8: Using SymmetricTensor objects directly
>>> site2 = Site(
...     isotope='13C',
...     isotropic_chemical_shift=20, # in ppm
...     shielding_symmetric=SymmetricTensor(zeta=10, eta=0.5)
... )

```

--------------------------------

### Set and print SpinSystem description

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Assign a description to the spin system.

```python
>>> sys1.description = "A test for the spin system"
>>> print(sys1.description)
A test for the spin system
```

--------------------------------

### Get Isotopes

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Retrieves a list of Isotope objects or symbols from the spin system based on spin quantum number.

```APIDOC
## GET /spin_systems/isotopes

### Description
Retrieves an ordered list of Isotope objects from the sites within the spin system corresponding to the given value of spin quantum number I. If I is None, a list of all Isotope objects is returned.

### Method
GET

### Endpoint
/spin_systems/isotopes

### Query Parameters
- **spin_I** (float) - Optional - An optional spin quantum number. The valid inputs are the multiples of 0.5.
- **symbol** (bool) - Optional - If true, return a list of str with isotope symbols.

### Response
#### Success Response (200)
- **isotopes** (list) - A list of Isotope objects or isotope symbols.

### Response Example
```json
{
  "isotopes": [
    "13C",
    "1H",
    "27Al"
  ]
}
```
```

--------------------------------

### Get Zeeman Energy States

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Retrieves all ZeemanState objects for a spin system, representing energy states as lists of quantum numbers.

```python
spin_system_1H_13C.zeeman_energy_states()  # four energy level system.
[|-0.5, -0.5⟩, |-0.5, 0.5⟩, |0.5, -0.5⟩, |0.5, 0.5⟩]
```

--------------------------------

### SpinSystem Methods

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Documentation for methods available on the SpinSystem object.

```APIDOC
## SpinSystem Methods

### all_transitions()

- **Description**: Returns a list of all possible spin Transition objects in the given spin system.
- **Returns**: A list of Transition objects.
- **Example**:
  ```python
  spin_system_1H_13C.all_transitions()  # 16 two energy level transitions
  # Output: [
  #   |-0.5, -0.5⟩⟨-0.5, -0.5|,
  #   |-0.5, 0.5⟩⟨-0.5, -0.5|,
  #   |0.5, -0.5⟩⟨-0.5, -0.5|,
  #   |0.5, 0.5⟩⟨-0.5, -0.5|,
  #   |-0.5, -0.5⟩⟨-0.5, 0.5|,
  #   |-0.5, 0.5⟩⟨-0.5, 0.5|,
  #   |0.5, -0.5⟩⟨-0.5, 0.5|,
  #   |0.5, 0.5⟩⟨-0.5, 0.5|,
  #   |-0.5, -0.5⟩⟨0.5, -0.5|,
  #   |-0.5, 0.5⟩⟨0.5, -0.5|,
  #   |0.5, -0.5⟩⟨0.5, -0.5|,
  #   |0.5, 0.5⟩⟨0.5, -0.5|,
  #   |-0.5, -0.5⟩⟨0.5, 0.5|,
  #   |-0.5, 0.5⟩⟨0.5, 0.5|,
  #   |0.5, -0.5⟩⟨0.5, 0.5|,
  #   |0.5, 0.5⟩⟨0.5, 0.5|
  # ]
  ```

### get_isotopes(_spin_I : Optional[float] = None_, _symbol : bool = False_) → list

- **Description**: Retrieves isotopes from the spin system.
- **Parameters**:
  - **spin_I** (float, optional): Filter by spin quantum number.
  - **symbol** (bool, optional): If True, return isotope symbols; otherwise, return atomic numbers. Defaults to False.
- **Returns**: A list of isotopes (atomic numbers or symbols).
```

--------------------------------

### Initialize SignalProcessor

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/signal_processor.html

Create a SignalProcessor instance by providing a list of operations to be applied to the dataset.

```python
>>> post_sim = SignalProcessor(operations=[o1, o2])
```

--------------------------------

### Get Isotopes from Spin System

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Retrieves a list of Isotope objects or their symbols from the spin system. Can filter by spin quantum number.

```python
>>> spin_systems.get_isotopes() # three spin systems
[Isotope(symbol='13C'), Isotope(symbol='1H'), Isotope(symbol='27Al')]
```

```python
>>> spin_systems.get_isotopes(symbol=True) # three spin systems
['13C', '1H', '27Al']
```

```python
>>> spin_systems.get_isotopes(spin_I=0.5) # isotopes with I=0.5
[Isotope(symbol='13C'), Isotope(symbol='1H')]
```

```python
>>> spin_systems.get_isotopes(spin_I=0.5, symbol=True) # isotopes with I=0.5
['13C', '1H']
```

```python
>>> spin_systems.get_isotopes(spin_I=1.5) # isotopes with I=1.5
[]
```

```python
>>> spin_systems.get_isotopes(spin_I=2.5) # isotopes with I=2.5
[Isotope(symbol='27Al')]
```

```python
>>> spin_systems.get_isotopes(spin_I=2.5, symbol=True) # isotopes with I=2.5
['27Al']
```

--------------------------------

### Set site description

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/site.html

Assign and retrieve the description for the site.

```python
>>> site.description = 'An example Quadrupolar site.'
>>> site.description
'An example Quadrupolar site.'
```

--------------------------------

### Get Isotopes by Spin Quantum Number

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Retrieves a list of isotopes matching a specific spin quantum number (spin_I). The result can be isotope objects or symbols.

```python
>>> sim.get_isotopes(spin_I=0.5)
[Isotope(symbol='13C'), Isotope(symbol='1H')]
>>> sim.get_isotopes(spin_I=0.5, symbol=True)
['13C', '1H']
```

```python
>>> sim.get_isotopes(spin_I=1.5)
[]
```

```python
>>> sim.get_isotopes(spin_I=2.5)
[Isotope(symbol='27Al')]
>>> sim.get_isotopes(spin_I=2.5, symbol=True)
['27Al']
```

--------------------------------

### SpinSystem Class Overview

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Overview of the SpinSystem class attributes and methods for managing spin system configurations.

```APIDOC
## SpinSystem Class

### Description
The SpinSystem class represents a collection of spin sites and their couplings. It is used to define the physical system for NMR simulations.

### Attributes
- **sites** (list) - A list of spin sites in the system.
- **couplings** (list) - A list of couplings between spin sites.
- **abundance** (float) - The relative abundance of the spin system.
- **name** (str) - The name of the spin system.
- **label** (str) - A label for the spin system.
- **description** (str) - A description of the spin system.
- **transition_pathways** (list) - The transition pathways defined for the system.

### Methods
- **all_transitions()** - Returns all transitions for the spin system.
- **get_isotopes()** - Returns the isotopes present in the system.
- **json()** - Returns a JSON representation of the spin system.
- **parse_dict_with_units()** - Parses a dictionary with units into a SpinSystem object.
- **reduced_dict()** - Returns a reduced dictionary representation.
- **rotate()** - Rotates the spin system.
- **simplify()** - Simplifies the spin system representation.
- **zeeman_energy_states()** - Calculates the Zeeman energy states.
```

--------------------------------

### POST /save

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Serializes the simulator object to a file.

```APIDOC
## POST /save

### Description
Serializes the current simulator object to a specified file.

### Method
POST

### Parameters
#### Request Body
- **filename** (str) - Required - The filename of the serialized file.
- **with_units** (bool) - Optional - If true, attribute values are serialized as physical quantities with units. If false, values are serialized as floats.

### Request Example
{
  "filename": "simulation.json",
  "with_units": true
}
```

--------------------------------

### Get Total Orientations Count

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator_config.html

Calculate the total number of orientations used for powder averaging based on integration density and volume. The formula depends on the integration volume.

```python
a = Simulator()
a.config.integration_density = 20
a.config.integration_volume = 'hemisphere'
a.config.get_orientations_count() # (4 * 21 * 22 / 2) = 924
```

--------------------------------

### Run simulation

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Executes the simulation to compute the spectrum. The `pack_as_csdm` parameter determines the output format. Optionally, pre-computed optimization data can be provided.

```python
>>> sim.run()
```

--------------------------------

### Set site label

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/site.html

Assign and retrieve the label for the site.

```python
>>> site.label = 'Quad site'
>>> site.label
'Quad site'
```

--------------------------------

### Set and print SpinSystem name

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Assign a name or ID to the spin system.

```python
>>> sys1.name = "1H-17O-0"
>>> print(sys1.name)
1H-17O-0
```

--------------------------------

### Initialize Site isotope

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/site.html

Set the isotope for a Site object using a string representation.

```python
>>> site = Site(isotope='2H')
```

--------------------------------

### Set site name

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/site.html

Assign and retrieve the name or ID of the site.

```python
>>> site.name = '2H-0'
>>> site.name
'2H-0'
```

--------------------------------

### Generate single-site spin systems

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/utils.html

Creates a list of single-site spin systems using various parameter configurations.

```python
>>> sys1 = single_site_system_generator(
...     isotope=["1H"],
...     isotropic_chemical_shift=10,
...     site_name="Single Proton",
... )
>>> print(len(sys1))
1
```

```python
>>> sys2 = single_site_system_generator(
...     isotope="1H",
...     isotropic_chemical_shift=[10] * 5,
...     site_name="5 Protons",
... )
>>> print(len(sys2))
5
```

```python
>>> Cq = [4.2e6] * 12
>>> sys3 = single_site_system_generator(
...     isotope="17O",
...     isotropic_chemical_shift=60.0,  # in ppm,
...     quadrupolar={"Cq": Cq, "eta": 0.5},  # Cq in Hz
... )
>>> print(len(sys3))
12
```

--------------------------------

### Configure Simulator Parameters

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator_config.html

Set various simulation parameters for the Simulator object, including number of sidebands, gamma angles, integration density, volume, and spectrum decomposition.

```python
a = Simulator()
a.config.number_of_sidebands = 128
a.config.number_of_gamma_angles = 10
a.config.integration_density = 96
a.config.integration_volume = 'hemisphere'
a.config.decompose_spectrum = 'spin_system'
```

--------------------------------

### Simulation Execution and Optimization

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Methods for running simulations and pre-computing transition pathways for efficiency.

```APIDOC
## run(method_index=None, n_jobs=1, pack_as_csdm=True, opt=None)

### Description
Run the simulation and compute spectrum.

### Parameters
#### Query Parameters
- **method_index** (list) - Optional - An integer or a list of integers to compute specific methods.
- **n_jobs** (int) - Optional - Number of jobs for parallel processing.
- **pack_as_csdm** (bool) - Optional - If true, results are stored as a CSDM object.
- **opt** (dict) - Optional - An optimization dictionary storing pre-computed transition pathways.

## optimize()

### Description
Pre-computes transition pathways and associated weights for each of the Method and SpinSystem objects held by the simulator to increase efficiency during minimization.
```

--------------------------------

### Simulator Loading and Saving

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Methods for loading Simulator objects from files and saving them to JSON format.

```APIDOC
## _load(filename, parse_units=True)

### Description
Load the Simulator object from a JSON file by parsing.

### Parameters
#### Query Parameters
- **filename** (str) - Required - The filename of a JSON serialized Simulator object file.
- **parse_units** (bool) - Optional - If true, parse the attribute values from the serialized file for physical quantities.

### Response
- **Simulator** (object) - A Simulator object.

## save(filename, with_units=True)

### Description
Serialize the simulator object to a JSON file.

### Parameters
#### Query Parameters
- **filename** (str) - Required - The filename to save the JSON serialized Simulator object.
- **with_units** (bool) - Optional - If true, the attribute value is a physical quantity expressed as a string with a number and a unit.
```

--------------------------------

### Parse Simulator Configuration from Dictionary

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator_config.html

Class method to create a ConfigSimulator object from a dictionary. This is useful for loading configurations from stored data.

```python
ConfigSimulator.parse_dict_with_units(json_dict)
```

--------------------------------

### Set Simulator Description

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Assigns a string description to the simulator instance.

```python
>>> sim.description = 'Simulation for sample 1'
>>> sim.description
'Simulation for sample 1'
```

--------------------------------

### Simulator Class Methods

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Documentation for the methods available in the Simulator class, including data export and isotope retrieval.

```APIDOC
## Simulator Class Methods

### export_methods

- **Description**: Export a list of methods to a JSON serialized file.
- **Parameters**:
  - **filename** (str) - A filename of the serialized file.
- **Example**:
```python
sim.export_methods(filename)
```

### export_spin_systems

- **Description**: Export a list of spin systems to a JSON serialized file.
- **Parameters**:
  - **filename** (str) - A filename of the serialized file.
- **Example**:
```python
sim.export_spin_systems(filename)
```

### get_isotopes

- **Description**: List of unique isotopes from the sites within the list of the spin systems corresponding to spin quantum number I. If I is None, a list of all unique isotopes is returned instead.
- **Parameters**:
  - **spin_I** (float, optional) - An optional spin quantum number. The valid input is the multiples of 0.5.
  - **symbol** (bool) - If true, return a list of str with isotope symbols.
- **Returns**: A list of Isotope objects.
- **Example**:
```python
# Get all unique isotopes
sim.get_isotopes()
# Get all unique isotope symbols
sim.get_isotopes(symbol=True)

# Get isotopes with spin_I = 0.5
sim.get_isotopes(spin_I=0.5)
# Get isotope symbols with spin_I = 0.5
sim.get_isotopes(spin_I=0.5, symbol=True)

# Get isotopes with spin_I = 2.5
sim.get_isotopes(spin_I=2.5)
# Get isotope symbols with spin_I = 2.5
sim.get_isotopes(spin_I=2.5, symbol=True)
```

### json

- **Description**: Parse the class object to a JSON compliant Python dictionary object.
- **Parameters**:
  - **exclude** (set, optional) - Set of keys that will be excluded from the result.
  - **units** (bool, optional) - Whether to include units in the output. Defaults to True.
- **Returns**: A dictionary representing the JSON object.
- **Example**:
```python
# Get JSON representation excluding 'spin_systems'
sim.json(exclude={'spin_systems'})

# Get JSON representation without units
sim.json(units=False)
```
```

--------------------------------

### Optimize simulator for efficiency

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Pre-computes transition pathways and weights to improve simulation efficiency during least-squared minimization. This method should be called before running the simulation if optimization is desired.

```python
>>> sim = Simulator()
>>> # Add spin systems and methods
>>> optimization = sim.optimize()
>>> sim.run(opt=optimization)
```

--------------------------------

### Load spin systems from JSON file

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Loads a list of spin systems from a specified JSON serialized file. Refer to the documentation for the expected file format.

```python
>>> sim.load_spin_systems(filename)
```

--------------------------------

### Set SpinSystem transition pathways

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Define transition pathways for the spin system using a list of dictionaries.

```python
>>> sys1.transition_pathways = [
...     [
...         {"initial": [-2.5, 0.5], "final": [2.5, 0.5]},
...         {"initial": [0.5, 0.5], "final": [-0.5, 0.5]}
...     ]
... ]
>>> print(sys1.transition_pathways)
[|2.5, 0.5⟩⟨-2.5, 0.5| ⟶ |-0.5, 0.5⟩⟨0.5, 0.5|, weight=(1+0j)]
```

--------------------------------

### Parsing and Data Loading

Source: https://mrsimulator.readthedocs.io/en/stable/genindex.html

Methods for parsing configurations and loading data into the simulator.

```APIDOC
## parse()

### Description
Parses input data or configurations for the simulator or specific components.

### Method
Class Method

## parse_dict_with_units()

### Description
Parses a dictionary containing unit-aware values to initialize various Mrsimulator objects.

### Method
Class Method
```

--------------------------------

### Simulator Class Reference

Source: https://mrsimulator.readthedocs.io/en/stable/_sources/api_py/simulator.rst.txt

Overview of the Simulator class, its inheritance, and available members.

```APIDOC
## Simulator Class

### Description
The Simulator class is the core component of the mrsimulator library, responsible for orchestrating simulation parameters and execution.

### Inheritance
- Inherits from: BaseModel

### Members
- The class includes all members defined within the Simulator module and inherited members from BaseModel.
```

--------------------------------

### Define SpinSystem sites

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Assign sites to a spin system using either Site objects or equivalent dictionaries.

```python
>>> sys1 = SpinSystem()
>>> sys1.sites = [Site(isotope="17O"), Site(isotope="1H")]
>>> # or equivalently
>>> sys1.sites = [{"isotope": "17O"}, {"isotope": "1H"}]
```

--------------------------------

### Serialization and Loading

Source: https://mrsimulator.readthedocs.io/en/stable/genindex.html

Methods for serializing objects to JSON and loading configurations or data into the Simulator.

```APIDOC
## json()

### Description
Serializes the object to a JSON representation.

### Method
Method

## load()

### Description
Loads data or configuration into the simulator environment.

### Method
Function/Class Method
```

--------------------------------

### ConfigSimulator Methods

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator_config.html

Methods available for the ConfigSimulator class.

```APIDOC
## ConfigSimulator Methods

### get_orientations_count()

#### Description
Return the total number of orientations.

#### Example
```python
a = Simulator()
a.config.integration_density = 20
a.config.integration_volume = 'hemisphere'
a.config.get_orientations_count() # (4 * 21 * 22 / 2) = 924
```

### json(_exclude = {}, _units = True_)

#### Description
Parse the class object to a JSON compliant Python dictionary object.

#### Parameters
- **exclude** (set) - Set of keys that will be excluded from the result.
- **units** (bool) - If true, the attribute value is a physical quantity expressed as a string with a number and a unit, else a float.

#### Returns
- dict: A dictionary representation of the class object.

### _classmethod _parse_dict_with_units(_json_dict_ : dict_)

#### Description
Parse the physical quantity from a dictionary representation of the class object, where the physical quantity is expressed as a string with a number and a unit.

#### Parameters
- **json_dict** (dict) - A required python dict object.

### reduced_dict(_exclude = {}_)

#### Description
Returns a reduced dictionary representation of the class object by removing all key-value pairs corresponding to keys listed in the exclude argument, and keys with a value of None.

#### Parameters
- **exclude** (list) - A list of keys to exclude from the dictionary.

#### Returns
- dict: A reduced dictionary representation of the class object.
```

--------------------------------

### Simulator Execution

Source: https://mrsimulator.readthedocs.io/en/stable/genindex.html

Methods for running simulations and managing the simulator configuration.

```APIDOC
## Simulator.run()

### Description
Executes the simulation based on the configured spin systems and methods.

### Method
Method

### Parameters
None specified.
```

--------------------------------

### Mrsimulator Simulation API Overview

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/py-simulator.html

This section provides an overview of the core components and utility functions available in the Mrsimulator Simulation API.

```APIDOC
## Mrsimulator Simulation API

This API provides tools for simulating NMR spectra.

### Core Objects

- **Simulator**: The main object for running simulations.
- **ConfigSimulator**: Configuration for the simulator.
- **CustomSampling**: For custom sampling methods.
- **SpinSystem**: Represents a spin system.
- **Site**: Represents a site within a spin system.
- **Coupling**: Represents spin-spin coupling.

### Method Objects

- **Method**: Defines the spectral acquisition method.
  - **SpectralDimension**: Defines a spectral dimension.
  - **Events**: Defines events within a method.
  - **FrequencyEnum**: Enum for frequency types.

### Query Objects

- **Query objects**: Used for querying spectral data.

### Other Objects

- **Sites**: Collection of sites.
- **ZeemanState**: Represents a Zeeman state.
- **SymmetricTensor**: Represents a symmetric tensor.
- **AntisymmetricTensor**: Represents an antisymmetric tensor.
- **Isotope**: Represents an isotope.
- **Transition**: Represents a spectral transition.
- **TransitionPathway**: Represents a pathway for transitions.
- **SymmetryPathway**: Represents a pathway related to symmetry.

### Utility Functions

- **`single_site_system_generator()`**: Generates a single-site spin system.
- **`site_generator()`**: Generates sites for a spin system.
- **`get_spectral_dimensions()`**: Retrieves spectral dimensions from a method.
- **Cartesian Tensor utils**: Utility functions for Cartesian tensors.

### Mrsimulator IO

- **`save()`**: Saves simulation data.
- **`dict()`**: Converts simulation objects to dictionaries.
- **`load()`**: Loads simulation data.
- **`parse()`**: Parses simulation data.
```

--------------------------------

### Set and print SpinSystem label

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Assign a label to the spin system.

```python
>>> sys1.label = "Heteronuclear spin system"
>>> print(sys1.label)
Heteronuclear spin system
```

--------------------------------

### SpinSystem Class Methods

Source: https://mrsimulator.readthedocs.io/en/stable/genindex.html

Methods for manipulating and querying spin systems.

```APIDOC
## SpinSystem.simplify()

### Description
Simplifies the spin system representation.

### Method
Method

## SpinSystem.zeeman_energy_states()

### Description
Calculates the Zeeman energy states for the spin system.

### Method
Method
```

--------------------------------

### Parse Spin System from Dictionary with Units

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Class method to parse a dictionary representation of a SpinSystem, where physical quantities are strings with numbers and units. Requires a dictionary as input.

```python
>>> spin_system_dict = {
...     "sites": [{
...         "isotope":"13C",
...         "isotropic_chemical_shift": "20 ppm",
...         "shielding_symmetric": {
...             "zeta": "10 ppm",
...             "eta": 0.5
...         }
...     }]
... }
>>> spin_system_1 = SpinSystem.parse_dict_with_units(spin_system_dict)
```

--------------------------------

### Retrieve Simulator sites

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Returns a list of unique Site objects contained within the Simulator instance.

```python
>>> sites = sim.sites()
```

--------------------------------

### Export Simulator Spin Systems

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Exports the list of spin systems configured for the simulator to a JSON serialized file.

```python
>>> sim.export_spin_systems(filename)
```

--------------------------------

### Save Simulator to file

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Serializes the simulator object to a file. The with_units parameter determines if values are saved as strings with units or as floats.

```python
>>> sim.save('filename')
```

--------------------------------

### Set SpinSystem abundance

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/spin_system.html

Set the abundance of the spin system in percentage.

```python
>>> sys1.abundance = 10
```

--------------------------------

### Simulator Class Methods

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Overview of the primary methods available for the Simulator object to manage simulation data and execution.

```APIDOC
## Simulator Class Methods

### Description
The Simulator class provides methods to configure, run, and export NMR simulations. It manages spin systems and experimental methods.

### Key Methods
- **run()**: Executes the simulation based on the configured spin systems and methods.
- **optimize()**: Performs optimization on the simulation parameters.
- **json()**: Returns a JSON representation of the simulator object.
- **save(filename)**: Saves the simulator configuration to a file.
- **load(filename)**: Loads a simulator configuration from a file.
- **export_methods()**: Exports the list of experimental methods.
- **export_spin_systems()**: Exports the list of spin systems.
- **get_isotopes()**: Retrieves the isotopes present in the simulation.

### Attributes
- **spin_systems**: List of spin systems involved in the simulation.
- **methods**: List of experimental methods to be simulated.
- **config**: Configuration settings for the simulation engine.
```

--------------------------------

### Add NMR Methods to Simulator

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Shows how to add NMR methods, such as BlochDecaySpectrum and BlochDecayCTSpectrum, to the simulator's methods list.

```python
>>> from mrsimulator.method.lib import BlochDecaySpectrum
>>> from mrsimulator.method.lib import BlochDecayCTSpectrum
>>> sim.methods = [
...     BlochDecaySpectrum(channels=['17O'], rotor_frequency=15000),
...     BlochDecayCTSpectrum(channels=['17O'])
... ]
```

--------------------------------

### Generate Single Site Spin Systems

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/utils.html

The `single_site_system_generator` function creates and returns a list of single-site spin systems based on the provided parameters.

```APIDOC
## POST /api/v1/single_site_system_generator

### Description
Generates and returns a list of single-site spin systems from the input parameters.

### Method
POST

### Endpoint
/api/v1/single_site_system_generator

### Parameters
#### Request Body
- **isotope** (Union[str, List[str]]) - Required - A string or a list of site isotopes.
- **isotropic_chemical_shift** (Union[float, List[float], ndarray]) - Optional - A float or a list/ndarray of isotropic chemical shifts per site per spin system. Defaults to 0.
- **shielding_symmetric** (Optional[Dict]) - Optional - A shielding symmetric dict object, where the keyword value can either be a float or a list/ndarray of floats. The allowed keywords are `zeta`, `eta`, `alpha`, `beta`, and `gamma`. Defaults to None.
- **shielding_antisymmetric** (Optional[Dict]) - Optional - A shielding antisymmetric dict object, where the keyword value can either be a float or a list/ndarray of floats. The allowed keywords are `zeta`, `alpha`, and `beta`. Defaults to None.
- **quadrupolar** (Optional[Dict]) - Optional - A quadrupolar dict object, where the keyword value can either be a float or a list/ndarray of floats. The allowed keywords are `Cq`, `eta`, `alpha`, `beta`, and `gamma`. Defaults to None.
- **abundance** (Optional[Union[float, List[float], ndarray]]) - Optional - A float or a list/ndarray of floats describing the abundance of each spin system.
- **site_name** (Optional[Union[str, List[str]]]) - Optional - A string or a list of strings with site names per site per spin system. Defaults to None.
- **site_label** (Optional[Union[str, List[str]]]) - Optional - A string or a list of strings with site labels per site per spin system. Defaults to None.
- **site_description** (Optional[Union[str, List[str]]]) - Optional - A string or a list of strings with site descriptions per site per spin system. Defaults to None.
- **rtol** (float) - Optional - The relative tolerance used in determining the cutoff abundance, given as, abundancecutoff=rtol*max(abundance). The spin systems with abundance below this threshold are ignored. Defaults to 0.001.

### Response
#### Success Response (200)
- **List[SpinSystem]** - A list of SpinSystem objects with a single Site.

### Request Example
```json
{
  "isotope": ["1H"],
  "isotropic_chemical_shift": 10,
  "site_name": "Single Proton"
}
```

### Response Example
```json
[
  {
    "site": {
      "isotope": "1H",
      "isotropic_chemical_shift": 10.0,
      "name": "Single Proton"
    },
    "abundance": 1.0
  }
]
```
```

--------------------------------

### Method Class Methods

Source: https://mrsimulator.readthedocs.io/en/stable/genindex.html

Common methods available across various Method classes in mrsimulator.

```APIDOC
## Method.shape()

### Description
Returns the shape of the method.

### Method
Method

## Method.summary()

### Description
Returns a summary of the method configuration.

### Method
Method
```

--------------------------------

### Generate Multiple Sites with Dictionary Arguments

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/utils.html

Generates multiple sites for a specific isotope ('17O') using dictionary arguments for quadrupolar parameters. This method is suitable for defining complex site properties, including quadrupolar interactions.

```python
>>> Cq = [4.2e6] * 12
>>> sys3 = site_generator(
...     isotope="17O",
...     isotropic_chemical_shift=60.0,  # in ppm,
...     quadrupolar={"Cq": Cq, "eta": 0.5},  # Cq in Hz
... )
>>> print(len(sys3))
12
```

--------------------------------

### Load methods from JSON file

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Loads a list of methods from a specified JSON serialized file. Ensure the file path is correct.

```python
>>> sim.load_methods(filename)
```

--------------------------------

### Load Simulator from JSON file

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Use this method to load a Simulator object from a JSON file. The `parse_units` parameter controls whether physical quantities are parsed from strings.

```python
>>> sim_1 = sim.load('filename')
```

--------------------------------

### Simulator Class Attributes

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Details on the attributes of the Simulator class, including spin_systems, methods, config, name, label, and description.

```APIDOC
## Simulator Class Attributes

### spin_systems

- **Type**: List[SpinSystem] or List[dict]
- **Description**: A list of SpinSystem or equivalent dict objects representing a collection of isolated NMR spin systems present within the sample. The default value is an empty list.
- **Example**:
```python
sim = Simulator()
sim.spin_systems = [
    SpinSystem(sites=[Site(isotope='17O')], abundance=0.015),
    SpinSystem(sites=[Site(isotope='1H')], abundance=1),
]
# or equivalently
sim.spin_systems = [
    {'sites': [{'isotope': '17O'}], 'abundance': 0.015},
    {'sites': [{'isotope': '1H'}], 'abundance': 1},
]
```

### methods

- **Type**: List[Method] or List[dict]
- **Description**: A list of Method or equivalent dict objects representing an NMR method. The default value is an empty list.
- **Example**:
```python
from mrsimulator.method.lib import BlochDecaySpectrum
from mrsimulator.method.lib import BlochDecayCTSpectrum
sim.methods = [
    BlochDecaySpectrum(channels=['17O'], rotor_frequency=15000),
    BlochDecayCTSpectrum(channels=['17O'])
]
```

### config

- **Type**: ConfigSimulator or dict
- **Description**: The ConfigSimulator object is used to configure the simulation. Valid attributes include `number_of_sidebands`, `integration_density`, `integration_volume`, and `decompose_spectrum`.
- **Example**:
```python
from mrsimulator.simulator.config import ConfigSimulator
sim.config = ConfigSimulator(
    number_of_sidebands=32,
    integration_density=64,
    integration_volume='hemisphere',
    decompose_spectrum='spin_system',
)
# or equivalently
sim.config = {
    'number_of_sidebands': 32,
    'integration_density': 64,
    'integration_volume': 'hemisphere',
    'decompose_spectrum': 'spin_system',
}
```

### name

- **Type**: str (optional)
- **Description**: The name or id of the simulation or sample. The default value is None.
- **Example**:
```python
sim.name = '1H-17O'
```

### label

- **Type**: str (optional)
- **Description**: The label for the simulation or sample. The default value is None.
- **Example**:
```python
sim.label = 'Test simulator'
```

### description

- **Type**: str (optional)
- **Description**: A description of the simulation or sample. The default value is None.
- **Example**:
```python
sim.description = 'Simulation for sample 1'
```
```

--------------------------------

### Set Simulator Label

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Assigns a string label to the simulator instance.

```python
>>> sim.label = 'Test simulator'
>>> sim.label
'Test simulator'
```

--------------------------------

### Export Simulator Methods

Source: https://mrsimulator.readthedocs.io/en/stable/api_py/simulator.html

Exports the list of methods configured for the simulator to a JSON serialized file.

```python
>>> sim.export_methods(filename)
```
Tokens:
Raw