# 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
```

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

## Usage
### 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.

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.

### 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.

## 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).