# Pyzfn

Pyzfn is a micromagnetic post-processing library designed for analyzing and visualizing data generated by [amumax](https://github.com/MathieuMoalic/amumax), a fork of [mumax3](http://mumax.github.io/). It provides a convenient interface for working with simulation data stored in [Zarr](https://zarr.readthedocs.io/en/stable/) format, offering optimized functions for data manipulation, spectral analysis, and visualization.

## Features

- **Easy Data Access**: Load and navigate large simulation datasets efficiently.
- **Spectral Analysis**: Calculate dispersion relations and extract spin wave modes.
- **Visualization Tools**: Generate snapshots and interactive spectral plots.
- **Integration with Zarr**: Leverage Zarr's capabilities for handling big data.

## Installation

Install Pyzfn using pip:

```bash
pip install pyzfn
```

## Usage

Pyzfn builds upon the functionalities provided by [Zarr](https://zarr.readthedocs.io/en/stable/). Familiarity with Zarr is recommended for advanced usage.

### Importing Pyzfn

```python
from pyzfn import Pyzfn
```

### Loading a Simulation

```python
# Replace 'path/to/job.zarr' with your simulation data path
job = Pyzfn('path/to/job.zarr')
```

### Exploring the Data Structure

#### Pretty Print the Data Tree

```python
# Interactive tree (requires IPython)
job.pp
```

#### Simple Data Tree Print

```python
# Non-interactive print
job.p
```

### Accessing Simulation Metadata

Simulation metadata is stored in the `.attrs` attribute:

```python
# Access metadata as a dictionary
dx = job.attrs['dx']

# Or as a class attribute (if no dataset shares the same name)
dx = job.dx
```

### Retrieving Simulation Data

Access datasets saved during the simulation:

```python
# Access magnetization data
# For example, get the x-component of magnetization for time steps 10 <= t < 20
# Dimensions are (time, z, y, x, component)
mag = job.m[10:20, :, :, :, 0]  # mag is a NumPy array
```

#### Lazy Loading

To handle large datasets without loading them into memory immediately:

```python
# Get a reference to the dataset
mag_dset = job.m

# Load data when needed
arr = mag_dset[:]
```

### Dataset Information

Display detailed information about a dataset:

```python
mag_dset.info
```

### Utilizing Help Functions

Use Python's built-in `help` and `dir` functions for assistance:

```python
help(mag_dset)
```

### Post-Processing Functions

Pyzfn provides optimized functions for common post-processing tasks.

#### Calculating Dispersion Relations

```python
# Calculate the dispersion relation for the magnetization dataset
job.calc_disp(dset_in_str='m', dset_out_str='m')
```

#### Calculating Spin Wave Modes

```python
# Extract spin wave modes from the data
job.calc_modes(dset_in_str='m', dset_out_str='m')
```

### Data Visualization

#### Snapshot Visualization

Generate a snapshot of the magnetization at a specific time step:

```python
# Visualize the magnetization at time index t=50 and layer z=0
job.snapshot(t=50, z=0)
```

#### Interactive Spectral Analysis

Launch an interactive FFT spectrum plot:

```python
# Interactive spectrum analysis
job.ispec(dset='m', c=0)
```

## Advanced Usage

### Custom Slicing

Optimize memory usage and performance with custom slicing:

```python
# Define custom slices for processing
slices = (
    slice(None),  # Time dimension
    slice(None),  # z dimension
    slice(None),  # y dimension
    slice(None),  # x dimension
    slice(None)   # Component dimension
)

# Calculate modes with custom slices
job.calc_modes(dset_in_str='m', dset_out_str='m', slices=slices)
```

### Saving and Loading OVF Files

Pyzfn includes utilities for working with OOMMF's OVF file format:

```python
from pyzfn.utils import save_ovf, load_ovf

# Save data to an OVF file
save_ovf('output.ovf', mag)

# Load data from an OVF file
data = load_ovf('output.ovf')
```

### Trimming Modes

Trim modes based on peak detection to reduce data size:

```python
# Trim modes with specified parameters
job.trim_modes(dset_in_str='m', dset_out_str='trimmed_m', peak_xcut_min=0)
```

## Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request on the [GitHub repository](https://github.com/mathieumoalic/pyzfn).


## Acknowledgments

- [amumax](https://github.com/MathieuMoalic/amumax) for simulation data.
- [Zarr](https://zarr.readthedocs.io/en/stable/) for efficient data handling.
