gbspy.surfaces module

class gbspy.surfaces.ChiLineSolver(sim, start, distance, resolution, bounds_error='throw', method='RK45')

Bases: IVPLineSolver

Solves a line along \(\nabla\Psi^T\).

class gbspy.surfaces.DummyLineSolver(coords, param)

Bases: LineSolver

A line solver that doesn’t solve anything

class gbspy.surfaces.IVPLineSolver(sim, start, distance, resolution, bounds_error='throw', method='RK45')

Bases: LineSolver

Initial value problem line solver

Solves a line by integration using scipy.integrate.solve_ivp(). The integrated function is typically a gradient passed as a callable.

class gbspy.surfaces.LineSolver(sim, start, distance, resolution, bounds_error='throw')

Bases: object

Base class for line solvers

Parameters

sim (gbspy.Sim) – Simulation object, which will be used to determine domain boundaries and magnetic geometry.
start (tuple of float) – A two-element tuple specifying the position at which to start the line in the poloidal plane, \((R,Z)\) coordinates.
distance (float) – How long the line should be in the poloidal plane, in units of \(\rho_{s0}\).
resolution (int) – Number of points to compute along the line.
bounds_error (str, optional) – By default ("throw"), the function will throw if the line intersects the boundary of the simulation domain. Other possible values include "ignore", where points will also be generated outside the domain, or "truncate" to stop generating the line at the domain boundary.

coords

Array containing the coordinates of points sampled along the traced line.

Type: numpy.ndarray

param

Array containing a variable that parametrizes the line, usually, the distance along the line in units of \(\rho_{s0}\).

Type: numpy.ndarray

compute(): Computes the line and sets coords and param.

class gbspy.surfaces.PsiLineSolver(sim, start, distance, resolution, bounds_error='throw', method='RK45')

Bases: IVPLineSolver

Solves a line along \(\nabla\Psi\).

class gbspy.surfaces.RLineSolver(sim, start, distance, resolution, bounds_error='throw')

Bases: RZLineSolver

Generates a radial line based on a linspace.

class gbspy.surfaces.RZLineSolver(sim, start, distance, resolution, bounds_error='throw')

Bases: LineSolver

Base class of line solver for radial and vertical lines

class gbspy.surfaces.ZLineSolver(sim, start, distance, resolution, bounds_error='throw')

Bases: RZLineSolver

Generates a vertical line based on a linspace.

gbspy.surfaces.connection_length(sim, start, reverse=False, not_connected_error=True, **kwargs)

Computes connection lengths between given starting points and the targets

Provided a simulation object and \((R,Z)\) coordinate pairs, follow the magnetic field line and integrate the connection length \(L_{\parallel}\) between this point and the target (simulation bounding box).

Parameters

sim (gbspy.pp.Sim) – Simulation object, from which the equilibrium magnetic flux function will be read.
start (array-like with shape (2,) or (N, 2)) – Starting coordinates for the line integrator, provided as tuples of \((R,Z)\) locations.
reverse (bool, optional) – If False, the connection length is computed following the poloidal magnetic field. If True, follows the opposite direction.
not_connected_error (bool, optional) – If True, an expection is thrown when starting points within closed field line regions are provided.

Returns

Connection lengths between the starting points and the targets. The result is returned in units of \(R_0\). If a single starting point was provided, a scalar is returned. If not_connected_error=False, the connection length returned with starting points associated to a closed field line region is np.NaN.

Return type

float or numpy.ndarray

gbspy.surfaces.get_line(sim, start, distance, direction, resolution=None, bounds_error='throw', **kwargs)

Grab a linear region in the poloidal plane of a simulation.

Traces a line in the poloidal plane and returns the 2D point coordinates along this line, as well as a parametrization variable. The parametrization is the length along the line (measured from the starting point) by default.

If distance is numeric, the line is traced in a single direction from the starting point. If the line should be traced in both directions, a tuple of two floats can be provided. If distance is a tuple and the resolution is provided, then resolution must also be a tuple of two floats.

Parameters

sim (gbspy.pp.Sim) – Simulation object in which to trace a line. The poloidal plane dimensions and magnetic equilibrium may be read from this object.
start (tuple of float or numpy.ndarray) – 2D coordinates of the starting point for the line, passed in order ‘xy’ (or ‘RZ’).
distance (float or tuple of float) – Defines the length of the line to be traced (in units of \(\rho_{s0}\)) from the starting point. The distance may be negative.
direction (str) – The direction that the line should follow. Can be 'R' (radial), 'Z' (vertical), 'psi' (cross field) or 'chi' (along field lines).
resolution (int or tuple of int, optional) – The number of points to place along the line. If distance is a tuple, resolution should also be a tuple. If None, points will be spaced based on the simulation’s grid steps.
bounds_error (str, optional) – By default, the solver will throw an exception if (a part of) the computed line lays outside of the simulation domain. To completely ignore the bounds, use 'ignore'. To automatically truncate the line when it reaches the bounding box, use 'truncate' (note this may adjust the resolution).
**kwargs (optional) – Solver specific options depending on the line direction chosen.

Returns

coords (numpy.ndarray) – Coordinate array of shape (2, N), where N is the number of points, along the line.
param (numpy.ndarray) – Parametrization variable along the line. The distance in the poloidal plane measured from the starting point is considered.

Examples

Considering that a simulation has been loaded already, we trace a line across flux surfaces. The line extends on both sides of the starting point.

>>> from gbspy.surfaces import get_line
>>> start_pt = (250, 400)
>>> coord, length = get_line(
...     sim, start_pt, (-20, 80), "psi", resolution=(10, 40)
... )

If we find out the line integrator is not precise enough (may be critical if direction='chi' near a separatrix), we can request a more precise integrator (by default, RK45 is used):

>>> coord, length = get_line(
...     sim, start_pt, (-20, 80), "psi", resolution=(10, 40), method="DOP853"
... )