Metadata-Version: 2.3
Name: pymagnetos
Version: 0.10b1
Summary: Applications for high magnetic field analysis
Author: Guillaume Le Goc
Author-email: Guillaume Le Goc <guillaume.le-goc@lncmi.cnrs.fr>
License: MIT
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: fftekwfm>=0.4.1
Requires-Dist: h5py>=3.16.0
Requires-Dist: hdf5plugin>=6.0.0
Requires-Dist: joblib>=1.5.3
Requires-Dist: numpy>=2.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyqt6==6.9.1
Requires-Dist: pyqtgraph>=0.14.0
Requires-Dist: rich>=14.3.3
Requires-Dist: scipy>=1.17.1
Requires-Dist: tomlkit>=0.14.0
Requires-Dist: typer>=0.24.1
Requires-Dist: mkdocstrings>=1.0.3 ; extra == 'docs'
Requires-Dist: mkdocstrings-python>=2.0.3 ; extra == 'docs'
Requires-Dist: zensical>=0.0.31 ; extra == 'docs'
Requires-Dist: ipympl>=0.10.0 ; extra == 'jupyter'
Requires-Dist: jupyter>=1.1.1 ; extra == 'jupyter'
Requires-Dist: matplotlib>=3.10.9 ; extra == 'jupyter'
Requires-Python: >=3.11
Project-URL: Source Code, https://gitlab.in2p3.fr/himagnetos/pymagnetos
Project-URL: Docs, https://himagnetos.pages.in2p3.fr/pymagnetos/index.html
Provides-Extra: docs
Provides-Extra: jupyter
Description-Content-Type: text/markdown

# pymagnetos
[![Latest Release](https://gitlab.in2p3.fr/himagnetos/pymagnetos/-/badges/release.svg)](https://gitlab.in2p3.fr/himagnetos/pymagnetos/-/releases) 
[![PyPI](https://img.shields.io/pypi/v/pymagnetos.svg?label=PyPI)](https://pypi.org/project/pymagnetos/)
[![Documentation](https://img.shields.io/website?label=Documentation&url=https%3A%2F%2Fhimagnetos.pages.in2p3.fr%2Fpymagnetos%2F)](https://himagnetos.pages.in2p3.fr/pymagnetos/)
[![Pipeline](https://gitlab.in2p3.fr/himagnetos/pymagnetos/badges/main/pipeline.svg?key_text=Pipeline)](https://gitlab.in2p3.fr/himagnetos/pymagnetos/-/pipelines)
![Coverage](https://gitlab.in2p3.fr/himagnetos/pymagnetos/badges/main/coverage.svg?job=test&key_text=Coverage)

Collection of Python tools for high magnetic field experiments analysis.

It provides libraries and apps to analyse data acquired at the LNCMI in Toulouse.

Currently available apps :
- `linx` : digital lock-in
- `pyuson` : for ultrasound experiments
- `pytdo` : for TDO experiments

Those are also available as a library that can be used within custom Python scripts. They use a common framework that can also be used to build other experiment-specific app.

The documention is hosted [here](https://himagnetos.pages.in2p3.fr/pymagnetos/).

## Installation
For more detailed instructions, see the [installation instructions](https://himagnetos.pages.in2p3.fr/pymagnetos/installation.html).

### Method 1 : as an app
If you plan to just use the graphical user interfaces, consider installing `pymagnetos` as a tool managed by [uv](https://docs.astral.sh/uv/), a modern Python package manager, that will install the required Python version and dependencies.

<details>
<summary>Method 1 : Click to see instructions</summary>

1. Install uv (see their official [installation instructions](https://docs.astral.sh/uv/getting-started/installation/)) :
    - On Windows, enter the following command in PowerShell :
    ```powershell
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```
    - On Linux and MacOS, enter the following in a shell :
    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
2. From a shell (PowerShell in Windows), install `pymagnetos` globally :
    ```bash
    uv tool install pymagnetos
    ```

`pymagnetos` is now installed along its dependencies in an isolated environment with no risks to mess up with your current tools and Python versions. Its main command, `pymagnetos`, is made available from any shell.

#### Update
To upgrade to the latest version, run :
```bash
uv tool upgrade pymagnetos
```
</details>

### Method 2 : as a library
Installing `pymagnetos` as a library will allow you to use it from scripts and Jupyter notebooks (e.g. you will be able to import it with `import pymagnetos`).

<details>
<summary>Method 2 : Click to see instructions</summary>

From a virtual environment with Python>=3.11, install `pymagnetos` from PyPI :
```bash
pip install pymagnetos
```

If you plan to use Jupyter notebooks, install `pymagnetos` with the Jupyter dependencies instead :
```bash
pip install pymagnetos[jupyter]
```

#### Update
To upgrade to the latest version, run, from the virtual environment :
```bash
pip install --upgrade pymagnetos
```
</details>

## Usage
All apps and the corresponding backend libraries require a configuration file. Grab a configuration file template from the [`configs`](https://gitlab.in2p3.fr/himagnetos/pymagnetos/-/tree/main/configs) folder, edit it according to your settings (essentially the path to the data directory) and drag & drop in the app window.

### Run an app
Once installed, the `pymagnetos` command should be available from the shell (PowerShell in Windows).
You can check its usage with :
`pymagnetos --help`

Which comes down to :
- Run the app for digital lock-in : `pymagnetos linx`
- Run the app for ultrasound experiments : `pymagnetos pyuson`
- Run the app for TDO experiments : `pymagnetos pytdo`

Tip : hit the top arrow on the keyboard to show previous commands you ran.

You can then drag & drop your configuration file in the window and click some buttons !

### Use in a script
Subpackages (e.g. `pyuson` or `pytdo`) can be imported in Python scripts or Jupyter notebooks. There are some examples in the [`examples`](https://gitlab.in2p3.fr/himagnetos/pymagnetos/-/tree/main/examples) folder. You can copy them and edit them according to your need.

To run the examples, `matplotlib` is required to display the figures. Install it with :
```bash
pip install matplotlib
```

To open and run the notebooks (file with the `.ipynb` extension), the Jupyter package needs to be installed, along with a package to make the figures interactive. If `pymagnetos` was installed with the `[jupyter]` extra, they are already installed. Otherwise, install those packages with :
```bash
pip install jupyter matplotlib ipympl
```

To open a Jupyter notebook, open the Jupyter Lab web interface :
```bash
jupyter lab
```

Then, browse to your `.ipynb` file and run it ! Alternatively, Visual Studio Code supports Jupyter notebooks natively through the Jupyter extension.

## Acknowledgments
`pymagnetos` is developed in the Laboratoire National des Champs Magnétiques Intenses ([LNCMI](https://lncmi.cnrs.fr/)) in Toulouse, France, with the support of the [OSCARS HiMagnetOS project](https://oscars-project.eu/projects/himagnetos-high-magnetic-field-open-science).