Metadata-Version: 2.1
Name: pyoculus
Version: 1.0.0
Summary: A Python version of Oculus - The eye into the chaos: a comprehensive magnetic field diagnostic package for non-integrable, toroidal magnetic fields
Author: Zhisong Zhu, Arunav Kumar, Stuart Hudson, Ludovic Rais
Author-Email: Christopher Berg Smiet <christopher.smiet@epfl.ch>
Maintainer: Zhisong Zhu
Maintainer-Email: Christopher Berg Smiet <christopher.smiet@epfl.ch>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numpy>1.21.1
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: dill
Provides-Extra: simsopt
Requires-Dist: simsopt; extra == "simsopt"
Provides-Extra: jax
Requires-Dist: jax; extra == "jax"
Description-Content-Type: text/markdown

# pyoculus

![version](https://img.shields.io/badge/version-1.0.0-blue)

The eye into chaos: a comprehensive diagnostic package for non-integrable, toroidal magnetic fields (and more general 1 1/2-D or 2D Hamiltonian system), analytic and more general maps that rely on integration. Started as a python version of the original package [Oculus](https://github.com/SRHudson/Oculus/). Oculus is the Latin word for *eye*.

> **Note: pyoculus 1.0.0 is a major rewrite with breaking API changes.**
> If your code targets the previous `Problem`/`Solver` API, pin to the last 0.3
> release:
> ```
> pip install pyoculus==0.3.3
> ```
> See the [CHANGELOG](CHANGELOG.md) for migration details.


## Package Installation

This fork of pyoculus is not uploaded to pypi, we recommend to install it directly from the git

```bash
git clone https://github.com/pyoculus/pyoculus.git
cd pyoculus
python -m pip install .
```

or for a specific user

```bash
git clone https://github.com/pyoculus/pyoculus.git
cd pyoculus
python -m pip install --user pyoculus
```

## SPEC

In this case, additional steps may be needed if you want to use [SPEC](https://princetonuniversity.github.io/SPEC/) are needed to compile the FORTRAN interfaces for SPEC magnetic field and 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/).

## Usage

At the core of pyoculus is the concept of a `Map`, that takes a point to a new point, e.g. $(R,Z)\rightarrow(\tilde{R},\tilde{Z})$. Here we used cylindrical coordinates $R, Z$, but any coordinates can be used, and there is even some functionality for higher-dimensional mappings.

A `Map` can be constructed in many ways, the simplest being iterated maps such as the `StandardMap` and `Tokamap`, in which the mapped-to point is evaluated from simple expressions. 
A `Map` can also be constructed from a magnetic field. In this case the map is defined by following integral curves of the field for a given number of symmetry periods.
In its setup, such an `IntegratedMap` needs properties of its integrator specified.
A map should provide a function `map.f(t,xx)`, that applies the map `t` times on the point `xx`, and `map.df` that provides the derivatives of the map (the Jacobian matrix).
More advanced maps can also provide a Lagrangian `map.lagrangian(y,t)`, that is needed for evaluating properties such as the turnstile area.

An `IntegratedMap` is generated from a `Field`, which is a vector field from $\mathbb{R}^3\rightarrow\mathbb{R}^3$.
There are separate classes for fields given in cylindrical or toroidal coordinates, and separate `Integrator` that can be applied to them to construct the map.
The fields can be instantiated from different outputs, including regular grids, and the output of specific simulation/equilibrium reconstruction software (M3DC-1, SPEC), and toy models given by analytical expressions in the `Toybox`.

With your favorite `map` in hand, you can analyze it with any of the `solvers`.

- `PoincarePlot`: Is instantiated with an array of starting points, and calling its `.compute(npts=1000)` will calculate all the trajectories from the list of starting points.
- `FixedPoint`: Finds fixed points of the map.
- `Manifold`: compute the intersections between manifolds of one or two fixed points, the tangles and turnstile areas.

There are also a few solvers that act on fields, such as `qfm` which finds quadratic flux minimizing surfaces in fields specified by toroidal coordinates using spectral methods.

## migrating from 0.3.x 

In older versions, the `Problem` is was directly and the integrator was specific to it. This meant that integrator parameters needed to be passed to every solver separately, and could lead to mismatches in solutions.

To adapt existing routines to the new `pyoculus` workflow, create a `Map` from your field, and pass the integration parameters (possibly in the `iparams` dictionary) as keyword arguments to its initialization. The Map will always use the same integration parameters and encapsulates the mapping from a Poincare section to itself. 

## Documentation

The documentation of pyoculus is managed by [Sphinx](https://www.sphinx-doc.org/) and can be found on [Github-Pages](https://akitzu.github.io/pyoculus/). This documentation will be updated regularly, however for latest features, you may need to research to the API Reference. You may also generate the documentation from source by following Sphinx's instructions.
