pyoculus 1.0.0

A Python version of Oculus - The eye into the chaos: a comprehensive magnetic field diagnostic package for non-integrable, toroidal magnetic fields

pyoculus

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. 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 for migration details.

Package Installation

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

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

or for a specific user

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

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 and can be found on Github-Pages. 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.