Metadata-Version: 2.1
Name: pyoculus
Version: 0.3.1
Summary: A Python version of Oculus - The eye into the chaos: a comprehensive magnetic field diagnostic package for non-integrable, toroidal magnetic fields
Home-page: https://github.com/zhisong/pyoculus
Author: Zhisong Qu, Arunav Kumar, Stuart Hudson
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License 
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/markdown
License-File: LICENSE

# pyoculus
A Python version of Oculus - The eye into the chaos: a comprehensive magnetic field diagnostic package for non-integrable, toroidal magnetic fields (and more general 1 1/2-D or 2D Hamiltonian system). Oculus is the Latin word for 'eye'.

## Installation

You can obtain the package from PYPI by

```
pip3 install pyoculus
```

or

```
pip3 install --user pyoculus
```

Alternatively, you can clone this repository. In this case, additional steps are needed to compile the FORTRAN interfaces for SPEC magnetic field and PJH. See below.

## Usage

To use the package, simply import it in Python:
```python
import pyoculus
```

Examples can be found in the `examples` subfolder.

## Documentation

The documentation of pyoculus is managed by [Doxygen](https://www.doxygen.nl/index.html).

You can find the documentation on Github Page: https://zhisong.github.io/pyoculus/

This documentation will be updated regularly but may not be most up-to-date. To generate the documentation from source, please run

```
make doxygen
```

The documentation will appear in the subfolder `doc/html`. Please open `doc/html/index.html` in your browser.

## SPEC magnetic field and Pressure Jump Hamiltonian (PJH) 

Some additional steps are needed to run pyoculus on outputs generated by 
the Stepped Pressure Equilibrium Code or [SPEC](https://princetonuniversity.github.io/SPEC/).

### Pre-requisite
You will need the `py_spec` package to read a SPEC output file and give it to pyoculus. However, `py_spec` is not a requirement for pyoculus. [Link to py_spec](https://pypi.org/project/py-spec/)

### Compilation
If you are not obtaining the package via PYPI, to use the pyoculus on SPEC magnetic field and PJH, please compile the Fortran modules for SPEC by
```
pip3 install -e .
```

Alternatively, you can manually compile `*.f90` in `pyoculus/problems/SPECfortran` using `f2py` to generate a module `pyoculus_spec_fortran_module`. This is not recommended.

Documentation for `f2py` can be found [here](https://numpy.org/doc/stable/f2py/).

## Developers
 - Zhisong Qu (zhisong.qu@anu.edu.au)
 - Arunav Kumar (arunav.kumar@anu.edu.au)
 - Stuart Hudson (shudson@pppl.gov)

## Link to the original Oculus package:

Github: https://github.com/SRHudson/Oculus

Documentation: https://w3.pppl.gov/~shudson/Oculus/oculus.pdf

