converters Module

Classes to convert between coordinate systems. Also contains routines for interpolating or downsampling in time.

class indica.converters.CoordinateTransform[source]

Class for converting between different coordinate systems. This is an abstract base class; each coordinate system should provide its own implementation.

Subclasses should allow each instance to have a “default grid” on which to calculate results. This can be cached for efficient retrieval.

Note that not all coordinate systems will have an actual x2 dimension (for example, the lines-of-site for soft X-ray data). However, 2 coordinates are still needed to map to the global coordinate system. Therefore, x2 is treated as a “pseudo-coordinate”,in these cases, with values between 0 and 1 specifying the position along the grid-line for x1. 0 is the start and 1 is the end (possibly overlapping, if the coordinate system is periodic).

Parameters

  • default_x1 – The default grid to use for the first spatial coordinate.

  • default_x1 – The default grid to use for the second spatial coordinate.

  • default_R – The default grid to use for the R-coordinate when converting to this coordinate system.

  • default_z – The default grid to use for the z-coordinate when converting to this coordinate system.

  • default_t – The default grid to use for time.

x1_name

Name for the first spacial coordinate. May be class- or instance-specific.

Type

str

x2_name

Name for the second spacial coordinate. May be class- or instance-specific.

Type

str

convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate. Each subclass must implement this method.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to(other, x1, x2, t)[source]

General routine to map coordinates from this system to those used in other. Array broadcasting will be performed as necessary.

If this transform class provides a specialised method for doing this (specified in _CONVERSION_METHODS) then that is used. Otherwise, the coordinates are converted to R-z using _convert_to_Rz() and then converted to the other coordinate system using _convert_from_Rz.

Parameters
Returns

  • x1 – The first spatial coordinate in the other system.

  • x2 – The second spatial coordinate in the other system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

abstract convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system. Each subclass must implement this method.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

static decode(json)[source]

Takes some JSON and decodes it into a CoordinateTransform object.

Parameters

json (str) –

Return type

indica.converters.abstractconverter.CoordinateTransform

distance(direction, x1, x2, t)[source]

Give the distance (in physical space) from the origin along the specified direction.

This is useful for when taking spatial integrals and differentials in that direction.

Note that distance is calculated using Euclidean lines between points. As such, it will not be accurate for a curved axis.

Parameters
Returns

Distance from the origin in the specified direction.

Return type

Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]

encode()[source]

Returns a JSON representation of this object. Should be sufficient to recreate it identically from scratch (except for the equilibrium).

Return type

str

get_converter(other, reverse=False)[source]

Checks if there is a shortcut to convert between these coordiantes, returning it if so. This can sometimes save the step of converting to (R, z) coordinates first.

Parameters
Returns

If a shortcut function is available, return it. Otherwise, None.

Return type

Optional[Callable[[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]], Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]]]

Note

Implementations should call other.get_converter(self, reverse=True. For obvious reasons, however, they should only do this when ``reverse == False``.

set_equilibrium(equilibrium, force=False)[source]

Initialise the object using a set of equilibrium data.

If it has already been initialised with the same equilibrium data then do nothing. If already initialised with a different equilibrium, throw an abstractconverter.EquilibriumException unless force == True.

Parameters

  • equilibrium (indica.abstract_equilibrium.AbstractEquilibrium) – A set of equilibrium data with which to calculate coordinate transforms.

  • force (bool) – If true, re-initialise the transform if provided with a new set of equilibrium data.

class indica.converters.EnclosedVolumeCoordinates(flux_surfaces)[source]

Class for polar coordinate systems using volume enclosed by flux surfaces as the radial coordinate.

Parameters
convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

get_converter(other, reverse=False)[source]

Checks if there is a shortcut to convert between these coordiantes, returning it if so. This can sometimes save the step of converting to (R, z) coordinates first.

Parameters
Returns

If a shortcut function is available, return it. Otherwise, None.

Return type

Optional[Callable[[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]], Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]]]

Note

Implementations should call other.get_converter(self, reverse=True. For obvious reasons, however, they should only do this when ``reverse == False``.

exception indica.converters.EquilibriumException[source]

Exception raised if a converter object’s equilibrium object is set twice.

class indica.converters.FluxMajorRadCoordinates(flux_surfaces)[source]

A coordinate system that uses a flux surface \(\rho\) and major radius to determine spatial positions. This is used, e.g., when estimating an emissivity profile of the plasma based on X-ray data. Note that this coordinate system loses information about vertical position. When converting to (R,z) coordinates, the results will have z >= 0.

Parameters

flux_surfaces (FluxSurfaceCoordinates) – The flux surface coordinate system to use for \(\rho\).

convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

get_converter(other, reverse=False)[source]

Checks if there is a shortcut to convert between these coordiantes, returning it if so. This can sometimes save the step of converting to (R, z) coordinates first.

Parameters
Returns

If a shortcut function is available, return it. Otherwise, None.

Return type

Optional[Callable[[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]], Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]]]

Note

Implementations should call other.get_converter(self, reverse=True. For obvious reasons, however, they should only do this when ``reverse == False``.

class indica.converters.FluxSurfaceCoordinates(kind)[source]

Class for polar coordinate systems using flux surfaces for the radial coordinate.

Parameters

kind (str) – The type of flux surface to use. Must be a valid argument for methods on the indica.equilibrium.Equilibrium class.

convert_from_Rz(R, z, t=None)[source]

Convert from the master coordinate system to this coordinate.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t=None)[source]

Convert from this coordinate to the R-z coordinate system.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

class indica.converters.ImpactParameterCoordinates(lines_of_sight, flux_surfaces, num_intervals=100, times=None)[source]

Class for coordinate systems based on lines-of-sight, but using the impact parameter (smallest flux value along a line-of-sight) as the label for the first coordinate.

Parameters
convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

distance(direction, x1, x2, t)[source]

Implementation of calculation of physical distances between points in this coordinate system. This accounts for potential toroidal skew of lines.

Parameters
Return type

Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]

drho()[source]

Calculates the average difference in impact parameters between adjacent lines of sight.

Return type

float

get_converter(other, reverse=False)[source]

Checks if there is a shortcut to convert between these coordiantes, returning it if so. This can sometimes save the step of converting to (R, z) coordinates first.

Parameters
Returns

If a shortcut function is available, return it. Otherwise, None.

Return type

Optional[Callable[[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]], Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]]]

Note

Implementations should call other.get_converter(self, reverse=True. For obvious reasons, however, they should only do this when ``reverse == False``.

rhomax()[source]

Returns the time-averaged maximum impact parameter on the low flux surface.

Return type

float

class indica.converters.LinesOfSightTransform(x_start, z_start, y_start, x_end, z_end, y_end, name, machine_dimensions=((1.83, 3.9), (- 1.75, 2.0)))[source]

Coordinate system for data collected along a number of lines-of-sight.

The first coordinate in this system is an index indicating which line-of-site a location is on. The second coordinate ranges from 0 to 1 (inclusive) and indicates the position of a location along the line-of-sight. Note that diagnostic using this coordinate system will usually only be indexed in the first coordinate, as the measurements were integrated along the line-of-sight.

If not passed to the constructor, the default grid for converting from the x-z system is chosen as follows:

  • The x-grid ranges from min(x_start.min(), x_end.min()) to max(x_start.max(), x_end.max()) with num_points intervals.

  • The z-grid ranges from min(z_start.min(), z_end.min()) to max(z_start.max(), z_end.max()) with num_points intervals.

Parameters

  • x_start (numpy.ndarray) – 1-D array of x positions of the start for each line-of-sight.

  • z_start (numpy.ndarray) – 1-D array of z positions of the start for each line-of-sight.

  • y_start (numpy.ndarray) – 1-D array of y positions for the start of each line-of-sight.

  • x_end (numpy.ndarray) – 1-D array of x positions of the end for each line-of-sight.

  • z_end (numpy.ndarray) – 1-D array of z positions of the end for each line-of-sight.

  • y_end (numpy.ndarray) – 1-D array of y positions for the end of each line-of-sight.

  • name (str) – The name to refer to this coordinate system by, typically taken from the instrument it describes.

  • machine_dimensions (Tuple[Tuple[float, float], Tuple[float, float]]) – A tuple giving the boundaries of the Tokamak in x-z space: ((xmin, xmax), (zmin, zmax). Defaults to values for JET.

convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate. Each subclass must implement this method.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system. Each subclass must implement this method.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

distance(direction, x1, x2, t)[source]

Implementation of calculation of physical distances between points in this coordinate system. This accounts for potential toroidal skew of lines.

Parameters
Return type

Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]

class indica.converters.MagneticCoordinates(z, name, machine_dimensions=((1.83, 3.9), (- 1.75, 2.0)))[source]

Class for transect-like coordinate systems using total magnetic field strength for location along the transect. The line of sight is assumed to be perfectly horizontal. The second coordinate in this system is the vertical offset from the line of sight (the argument for which would typically be 0 when converting to Rz coordinates).

Parameters

  • z (float) – The vertical position of the line of sight along which measurements are taken. Used as default z position.

  • name (str) – The name for this coordinate system. Typically taken from the instrument these coordinates are for.

  • machine_dimensions (Tuple[Tuple[float, float], Tuple[float, float]]) – A tuple giving the boundaries of the Tokamak in R-z space: ((Rmin, Rmax), (zmin, zmax). Defaults to values for JET.

convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

class indica.converters.TransectCoordinates(R_positions, z_positions)[source]

Coordinate system for measurements taken along a 1-D line through the Tokamak.

The first spatial position corresponds to an arbitrary index along the length of the transect. The second is the vertical offset from the transect. Typically, all data will fall directly on the transect, but it is useful to have the second coordinate so that the system is general and to allow conversions to other systems.

The coordinates along the transect are the indices of the positions provided when intialisign the object.

The default grid for coordinate transforms in this system is a 1-D array corresponding to the positions along the axis specified in the parmeters used to intialise the object.

The implementation currently makes use of interpolation, so that it is completely general for nonuniformly spaced points and even for a curved line (although the latter would be only approximated). However, this has some computational overhead, so it may be changed in future.

Parameters
convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

class indica.converters.TrivialTransform[source]

Class to use for transforms to/from an R-z coordinate systems. This is trivial, as R-z coordinates are the go-between for conversion to all other coordinate systems.

convert_from_Rz(R, z, t)[source]

Convert from the master coordinate system to this coordinate.

Parameters
Returns

  • x1 – The first spatial coordinate in this system.

  • x2 – The second spatial coordinate in this system.

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

convert_to_Rz(x1, x2, t)[source]

Convert from this coordinate to the R-z coordinate system.

Parameters
Returns

  • R – Major radius coordinate

  • z – Height coordinate

Return type

Tuple[Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable], Union[float, int, numpy.ndarray, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset, xarray.core.variable.Variable]]

indica.converters.bin_to_time_labels(tlabels, data)[source]

Bin data to sit on the specified time labels.

Parameters
Returns

Array like the input, but binned onto the time labels.

Return type

xarray.core.dataarray.DataArray

indica.converters.convert_in_time(tstart, tend, frequency, data, method='linear')[source]

Interpolate or bin (as appropriate) the given data along the time axis, discarding data before or after the limits.

Parameters

  • tstart (float) – The lower limit in time for determining which data to retain.

  • tend (float) – The upper limit in time for determining which data to retain.

  • frequency (float) – Frequency of sampling on the time axis.

  • data (xarray.core.dataarray.DataArray) – Data to be interpolated/binned.

  • method (Union[Literal['linear', 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'polynomial'], typing.Literal['barycentric', 'krog', 'pchip', 'spline', 'akima']]) – Interpolation method to use. Must be a value accepted by scipy.interpolate.interp1d.

Returns

Array like the input, but interpolated or binned along the time axis.

Return type

xarray.core.dataarray.DataArray