fusionsc.flt

Functions for field-line tracing and interpretation of traces.

Functions

axisCurrent(field, current[, grid, ...])	Configuration that places a current on the axis of a given magnetic configuration.
calculateFourierModes(field, startPoints, ...)	Note Has asynchronous variant '.asnc(...)' that returns Promise[...]
calculateIota(field, startPoints, turnCount)	Note Has asynchronous variant '.asnc(...)' that returns Promise[...]
computeMapping(field, mappingPlanes, r, z[, ...])	Computes a reversible field line mapping. This mapping type divides the device into toroidal
connectionLength(points, config, geometry, ...)	Computes the connection-length of the given points in a certain geometry.
decodeTraceResponse(response[, resultFormat])	Decodes an FLT response according to the requested format.
fieldValues(config, grid)	DEPRECATED & SLATED FOR REMOVAL IN 3.0
findAxis(field[, grid, startPoint, ...])	Computes the magnetic axis by repeatedly tracing a Poincaré map and averaging the points.
findLCFS(field, geometry, p1, p2[, grid, ...])	Compute the position of the last closed flux surface
followFieldlines(points, config[, recordEvery])	Follows magnetic field lines.
poincareInPhiPlanes(points, config, ...)	Computes the Poincaré map starting from a given set of points on a config.
symmetrize(points[, nSym, stellaratorSymmetric])	Takes a point-cloud and creates a new point cloud obeying the prescribed discrete symmetry by applying all corresponding discrete transformations (phi-shifts and flips).
trace(points, config[, geometry, grid, ...])	Performs a tracing request.

Classes

FieldlineMapping(dataOrRef)

A storage container for a mapping offering load / save methods

Functions

fusionsc.flt.axisCurrent(field, current, grid=None, startPoint=None, stepSize=0.001, nTurns=10, nIterations=10, nPhi=200, direction=None, mapping=None, targetError=None, relativeErrorTolerance=1, minStepSize=0, maxStepSize=0.2) → Any

Configuration that places a current on the axis of a given magnetic configuration.

This function computes the magnetic axis of a magnetic configuration, interprets it as a coil, and creates a magnetic configuration with a given current specified on this axis.

Parameters:

field: Magnetic field configuration current: On-axis current to apply grid: Grid to use for magnetic field calculation if the field is not yet computed

Returns:

The magnetic configuration corresponding to the on-axis current’s field.

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.calculateFourierModes(field, startPoints, turnCount, nMax=1, mMax=1, toroidalSymmetry=1, aliasThreshold=None, grid=None, stellaratorSymmetric=False, unwrapEvery=1, recordEvery=10, distanceLimit=0, targetError=0.0001, relativeErrorTolerance=1, minStepSize=0, maxStepSize=0.2, islandM=1) → Any

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.calculateIota(field, startPoints, turnCount, grid=None, axis=None, unwrapEvery=1, distanceLimit=10000.0, targetError=0.0001, relativeErrorTolerance=1, minStepSize=0, maxStepSize=0.2, islandM=1) → Any

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.computeMapping(field, mappingPlanes, r, z, grid=None, distanceLimit=1000.0, padding=2, numPlanes=20, stepSize=0.001, u0=[0.5], v0=[0.5]) → Any

Computes a reversible field line mapping. This mapping type divides the device into toroidal sections. Each section is covered by a curved conforming hexahedral grid. The “mapping planes” define the toroidal sections at which the different sections meet. Within a sections, field lines can be interpolated in the r-z plane using phi-independent u,v coordinates on the grid. When crossing into other sections, the field line mapping must be inverted to construct new grid coordinates.

The tracing of the sections is started from planes lying in-between the mapping planes.

Parameters:

• field: A magnetic field to create the mapping over.

• mappingPlanes: An array-like of radial angles. Must be in counterclockwise order (but can start and stop anywhere)

• r: Major radius values of the starting points to trace the grid from

• z: Z coordinate values of the starting points to trace the grid from

• grid: Grid to use for field computation (if field is not computed yet)

• distanceLimit: Maximum field line length to trace. Can often be reduced aggressively.

• padding: Number of planes to add beyond the mapping planes on each section. Currently must be at least 2.

• numPlanes: Number of planes to record for each half-section trace.

• stepSize: Step size to use for tracing.

• u0 (number or sequence of numbers, ranging from 0 to 1): Per-section starting grid coordinates for mapping, radial component

• v0 (number or sequence of numbers, ranging from 0 to 1): Per-section starting grid coordinates for mapping, vertical component

Returns:

A DataRef pointing to a to-be-initialized field line mapping.

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.connectionLength(points, config, geometry, **kwargs) → Any

Computes the connection-length of the given points in a certain geometry.

Mostly equivalent to trace(points, config, geometry = geometry, collisionLimit = 1, **kwargs)["endPoints"][3].

Parameters:

• points: Starting points for the trace. Can be any shape, but the first dimension must have a size of 3 (x, y, z).

• config: Magnetic configuration. If this is not yet computed, you also need to specify the ‘grid’ parameter.

• geometry: Device geometry. If this is not yet indexed, you need to specify the ‘geometryGrid’ parameter (see the documentation of trace).

Returns:

An array of shape points.shape[1:] indicating the forward connection length of the given point.

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.decodeTraceResponse(response: ReaderOrBuilder, resultFormat: str = 'dict')

Decodes an FLT response according to the requested format.

fusionsc.flt.fieldValues(config, grid) → Any

DEPRECATED & SLATED FOR REMOVAL IN 3.0

Use fusionsc.magnetics.MagneticConfig.getComputed(…) instead, which uses the fusionsc field convention of [grid.nPhi, grid.nZ, grid.nR, 3].

Obtains the magnetic field of a configuration on a specific grid.

Parameters:

• config: Description of the magnetic field

• grid: Grid to compute the field on.

Returns:

An array of shape [3, grid.nPhi, grid.nZ, grid.nR] containing the magnetic field. The directions along the first coordinate are phi, z, r.

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.findAxis(field, grid=None, startPoint=None, stepSize=0.001, nTurns=10, nIterations=10, nPhi=200, direction='ccw', mapping=None, targetError=None, relativeErrorTolerance=1, minStepSize=0, maxStepSize=0.2, islandM=1) → Any

Computes the magnetic axis by repeatedly tracing a Poincaré map and averaging the points.

Returns:

A tuple holding the xyz-position of the axis starting point and a numpy array holding the field line corresponding to the magnetic axis.

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.findLCFS(field, geometry, p1, p2, grid=None, geometryGrid=None, stepSize=0.01, tolerance=0.001, nScan=8, distanceLimit=3000.0, mapping=None, targetError=None, relativeErrorTolerance=1, minStepSize=0, maxStepSize=0.2) → Any

Compute the position of the last closed flux surface

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.followFieldlines(points, config, recordEvery=1, **kwargs) → Any

Follows magnetic field lines.

Mostly equivalent to (lambda x: return x["fieldLines"], x["fieldStrengths"])(trace(points, config, recordEvery, **kwargs)).

Parameters:

• points: Starting points for the trace. Can be any shape, but the first dimension must have a size of 3 (x, y, z).

• config: Magnetic configuration. If this is not yet computed, you also need to specify the ‘grid’ parameter.

• recordEvery: Number of tracing steps between each recorded point.

Returns:

A tuple holding: - An array of shape points.shape + [max. field line length] indicating the field line point locations - An array of shape points.shape[1:] + [max. field line length] indicating the field strength at those points

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.poincareInPhiPlanes(points, config, phiPlanes, turnLimit, **kwArgs) → Any

Computes the Poincaré map starting from a given set of points on a config.

Mostly equivalent to trace(points, config, phiPlanes = phiPlanes, turnLimit = turnLimit, **kwArgs)["poincareHits"].

Parameters:

• points: Starting points for the trace. Can be any shape, but the first dimension must have a size of 3 (x, y, z).

• phiPlanes: 1D list of intersection plane angles (in radian)

• config: Magnetic configuration. If this is not yet computed, you also need to specify the ‘grid’ parameter (see the documentation of trace).

Returns:

An array of shape [5, len(phiPlanes)] + points.shape[1:] + [turnLimit]. The entries in dimension 1 are [x, y, z, forward connection length, backward connection length]. If the forward- or backward-going field lines from this point hit no geometry, the returned length will be negative and its absolute magnitude will indicate the remaining field line length in that direction.

For the extra arguments, see the parameters to trace().

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]

fusionsc.flt.symmetrize(points, nSym=1, stellaratorSymmetric=False)

Takes a point-cloud and creates a new point cloud obeying the prescribed discrete symmetry by applying all corresponding discrete transformations (phi-shifts and flips).

Parameters:

• points: A numpy-array of shape [3, …] (at least 1D) with the points in x, y, z coordinates.

• nSym: Toroidal symmetry to be applied to the cloud.

• stellaratorSymmetric: Whether to apply the Stellarator symmetry (phi -> -phi, z -> -z, r -> r) as well.

Returns:

An array of shape [3, nTotalSym] + points.shape[1:] containing the new point cloud with nTotalSym = 2 * nSym if stellaratorSymmetric else nSym

fusionsc.flt.trace(points, config, geometry=None, grid=None, geometryGrid=None, mapping=None, distanceLimit=10000.0, turnLimit=0, stepLimit=0, stepSize=0.001, collisionLimit=0, phiPlanes=[], isotropicDiffusionCoefficient=None, rzDiffusionCoefficient=None, parallelConvectionVelocity=None, parallelDiffusionCoefficient=None, meanFreePath=1, meanFreePathGrowth=0, direction='forward', recordEvery=0, resultFormat='dict', targetError=None, relativeErrorTolerance=1, minStepSize=0, maxStepSize=0.2, errorEstimationDistance=None, ignoreCollisionsBefore=0) → Any

Performs a tracing request.

Parameters:

• points: Starting points. Array-like of shape [3, …] (must be at least 1D, first dimension is x, y, z).

• config (magnetics.MagneticConfig): Magnetic configuration. If this is not yet computed, you must specify the ‘grid’ parameter.

• geometry (geometry.Geometry): Geometry to use for intersection tests of field lines. If this is not yet indexed, you must specify the ‘geometryGrid’ parameters.

• grid (service.ToroidalGrid.Reader or service.ToroidalGrid.Builder): Toroidal grid to compute the magnetic field on prior to tracing.

• geometryGrid (service.CartesiaGrid.Reader or service.CartesianGrid.Builder): Cartesian grid to index the geometry triangles on (used to accelerate intersection computations).

• distanceLimit: Maximum field line tracing length. 0 or negative interpreted as infinity.

• turnLimit: Maximum number of device turn to trace field line for. 0 or negative interpreted as infinity.

• stepLimit: Maximum number of steps to trace for. 0 interpreted as infinity. May not be negative.

• stepSize: Step size for each tracing step (in meters).

• collisionLimit: Maximum number of collisions a field line may perform (e.g. 1 = termination at first collision. 2 at second collision etc.). Must not be negative. 0 interpreted as infinity.

• phiPlanes (list(float)): Phi values (in radians) at which to record field line intersections (usually for the purpose of Poincaré maps).

• isotropicDiffusionCoefficient: If set, enables diffusive tracing and specifies the isotropic / perpendicular diffusion coefficient to use in the underlying diffusive tracing model. If set, either parallelConvectionVelocity or parallelDiffusionCoefficient must also be specified.

• rzDiffusionCoefficient: Similar to isotropicDiffusionCoefficient, but displacements are only done in the rz plane

• parallelConvectionVelocity: Parallel streaming velocity to assume for a single-directional diffusive tracing model.

• parallelDiffusionCoefficient: Parallel diffusion coefficient to assume for a fully bidireactional doubly-diffusive tracing model.

• meanFreePath: Mean (not fixed!) free path to use to sample the tracing distance between diffusive displacement steps.

• meanFreePathGrowth: Amount by which to increase the mean free path after every displacement step. This parameter prevents extreme growths of computing costs at low perpendicular diffusion coefficients.

• mapping: Field line mapping to accelerate tracing.

• direction: Indicates the tracing direction. One of “forward” (field direction), “backward” (against field), “cw” (clockwise), or “ccw” (counter-clockwise)

• recordEvery: When set to > 0, instructs the tracer to record the fieldline every “recordEvery”-th step.

• targetError: Step size to adjust steps towards.

• relativeErrorTolerance: If the error estimator indicates that the error is more than targetError * (1 + relativeErrorTolerance), the step will be repeated with adjusted step size. Otherwise, the adjusted step size will be used for the next step.

• minStepSize: Minimum step size for adaptive controller

• maxStepSize: Maximum step size for adaptive controller

• errorEstimationDistance: Maximum trace length to be assumed for the purpose of error estimation. If this is not set, the service will try to estimate it from the limits. Can be set to “step” to indicate per-step error targets.

• ignoreCollisionsBefore: Minimum distance to trace before collisions will be actively processed. Useful when starting a trace on / very close to a mesh and not wanting to immediately have this mesh terminate the trace.

Returns:

The format of the result depends on the resultFormat parameter.

• If resultFormat == ‘dict’:

  A dictionary holding the following entries (more can be added in future versions)

  • endPoints: A numpy array of shape [4] + startPoints.shape[1:]. The first 3 components are the x, y, and z positions of the field lines’ end points. The 4th component is the total length of the field line.

  • poincareHits: A numpy array of shape [5, len(phiPlanes)] + startPoints.shape[1:] + [maxTurns] with maxTurns being a number <= turnLimit indicating the maximum turn count of any field line. The first 3 components of the first dimension are the x, y, and z coordinates of the phi plane intersections (commonly used for Poincaré maps). The next two components indicate the forward and backward connection lengths respectively to the next geometry collision along the field line. If the field line ends in that direction without a collision (e.g. closed field line, or no geometry specified), a negative number is returned whose absolute value corresponds to the remaining length in that direction. Non-existing points (due to field lines not all having same turn counts) have their values set to NaN.

  • stopReasons: A numpy array of shape startPoints.shape[1:] that indicates for each point the final reason why the trace was stopped. The dtype of the array is fusionsc.service.FLTStopReason.

  • fieldLines: A numpy array of shape startPoints.shape + [max. field line length] containing steps recorded at specified intervals (see parameter `recordEvery. Padded with NaN.

  • fieldStrengths: A numpy array of shape startPoints.shape[1:] + [max. field line length] holding the absolute magnetic field strength at the recorded field line points. Padded with 0.

  • endTags: A dict containing a numpy array of type fusionsc.service.TagValue for each tag name present in the geometry. Each array is of shape startPoints.shape[1:], and its values indicate the tags associated with the final geometry hit. This gives information about the meshes impacted by the field lines.

  • responseSize: The total size of the response size in bytes (mainly for profiling purposes).

• If resultFormat == ‘raw’:

  An instance of fusionsc.service.FLTResponse.Reader (for more efficient storage and later decoding).

Note Has asynchronous variant ‘.asnc(…)’ that returns Promise[…]