Metadata-Version: 2.4
Name: fsl-denmatsim
Version: 2.0.0
Summary: Density matrix simulations for FSL-MRS sequence modelling.
License: BSD 3-Clause License
        
        Copyright (c) 2026, William Clarke, University of Oxford
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Dynamic: license-file

# fsl-denmatsim

`fsl-denmatsim` is a small Python library for density-matrix simulation of NMR/MRS pulse sequences. It is aimed at FSL-MRS sequence modelling workflows and includes:

- spin-system definitions for common in vivo metabolites;
- sequence simulation through `simseq`;
- RF, gradient, delay/rephase, coherence-filter, and readout handling;
- packaged example sequence descriptions;
- regression tests and lightweight benchmarks for the supported simulation paths.

The package currently supports one-dimensional projection, interleaved spatial simulation, and full spatial simulation modes.

## Repository Layout

- `src/fsl_denmatsim/`: package source code.
- `src/fsl_denmatsim/spinSystems.json`: original built-in spin-system definitions.
- `src/fsl_denmatsim/spinSystemsSplit.json`: equivalent split spin-system definitions.
- `src/fsl_denmatsim/sequence_examples/`: packaged example sequence JSON files.
- `tests/`: pytest regression and unit tests.
- `benchmarks/`: simple runtime and memory benchmark script.

## Development With Pixi

This project uses [Pixi](https://pixi.sh/) to manage the development environment.

Install the environment:

```bash
pixi install
```

Run the test suite:

```bash
pixi run test
```

Run all tests, including tests marked as slow:

```bash
pixi run test-all
```

Run linting and formatting:

```bash
pixi run lint
pixi run format
```

Run the benchmark suite:

```bash
pixi run benchmark
```

Include slower benchmark cases:

```bash
pixi run benchmark-slow
```

## Basic Usage

The main entry point is `fsl_denmatsim.simseq.simseq`, which takes a spin-system dictionary and a sequence-parameter dictionary.

```python
import json
from importlib.resources import files

from fsl_denmatsim.simseq import simseq

package_files = files("fsl_denmatsim")

spin_systems = json.loads(package_files.joinpath("spinSystems.json").read_text())
params = json.loads(
    package_files.joinpath("sequence_examples", "example.json").read_text()
)

spinsys = spin_systems["sysGlu"]

fid, axes, final_density_matrix = simseq(spinsys, params, verbose=False)
```

For metabolites represented by multiple independent sub-systems, simulate each sub-system and combine the scaled FIDs:

```python
import numpy as np

systems = spinsys if isinstance(spinsys, list) else [spinsys]
fids = []

for system in systems:
    fid, axes, final_density_matrix = simseq(system, params, verbose=False)
    fids.append(fid * system["scaleFactor"])

combined_fid = np.sum(fids, axis=0)
```

The helper functions in `fsl_denmatsim.utils` provide this scaling pattern for some workflows.

## Further documentation
For context around the simulator in the FSL-MRS package see the [online documentation](https://open.oxcin.ox.ac.uk/pages/fsl/fsl_mrs/simulation.html)
## Sequence Parameters

Sequence descriptions are JSON-compatible dictionaries. Packaged examples live in:

- `sequence_examples/example.json`
- `sequence_examples/example_slaser.json`

The simulator expects sequence fields such as:

- `B0`
- `Rx_Points`, `Rx_SW`, `Rx_LW`, `Rx_Phase`
- spatial bounds and `resolution`
- `RF`, `delays`, `rephaseAreas`, and `CoherenceFilter`
- unit fields such as `RFUnits`, `GradUnits`, and `spaceUnits`

See the [online FSL-MRS Documentation](https://open.oxcin.ox.ac.uk/pages/fsl/fsl_mrs/seq_file_params.html#seq-file-params) for a list.

## License

This project is distributed under the BSD 3-Clause License. See [LICENSE](LICENSE).
