7.1. Core Plasma Classes¶

7.1.1. Main Plasma Object¶

class cherab.core.Plasma¶

A scene-graph object representing a plasma.

The Cherab Plasma object holds all the properties and state of a plasma and can optionally have emission models attached to it.

To define a Plasma object you need to define the plasma composition, magnetic field and electron distribution. The Plasma composition consists of a collection of Species objects that define the individual distribution functions of specific neutral atoms or ions in the plasma. Each individual species can only appear once in the composition. For more information see the related objects, Species, Composition, and DistributionFunction. To define the magnetic field you must provide a function that returns a magnetic field vector at the requested coordinate in the local plasma coordinate system.

The Plasma object is a Raysect scene-graph Node and lives in it’s own coordinate space. This coordinate space is defined relative to it’s parent scene-graph object by an AffineTransform. The plasma parameters are defined in the Plasma object coordinate space. Models using the plasma object must convert any spatial coordinates into plasma space before requesting values from the Plasma object.

While a Plasma object can be used to simply hold and sample plasma properties, it can also be used as an emitter in Raysect scenes by attaching geometry and emission models. To add emission models you first need to define a bounding geometry for the plasma. The geometry is described by a Raysect Primitive. The Primitive may be positioned relative to the plasma coordinate system by setting the geometry_transform attribute. If no geometry transform is set, the Primitive will share the same coordinate system as the plasma.

Once geometry is defined, plasma emission models may be attached to the plasma object by either setting the full list of models or adding to the list of models. See the ModelManager for more information. The plasma emission models must be derived from the PlasmaModel base class.

Any change to the plasma object including adding/removing of species or models will result in a automatic notification being sent to objects that register with the Plasma objects’ Notifier. All Cherab models and associated scene-graph objects such as Beams automatically handle the notifications internally to clear cached data. If you need to keep track of plasma changes in your own classes, a callback can be registered with the plasma Notifier which will be called in the event of a change to the plasma object. See the Notifier documentation.

Parameters

parent (Node) – The parent node in the Raysect scene-graph. See the Raysect documentation for more guidance.
transform (AffineMatrix3D) – The transform defining the spatial position and orientation of this plasma. See the Raysect documentation if you need guidance on how to use AffineMatrix3D transforms.
name (str) – The name for this plasma.
integrator (VolumeIntegrator) – The configurable method for doing volumetric integration through the plasma along a Ray’s path. Defaults to a numerical integrator with 1mm step size, NumericalIntegrator(step=0.001).

Variables

atomic_data (AtomicData) – The atomic data provider class for this plasma. All plasma emission from this plasma will be calculated with the same provider.
b_field (VectorFunction3D) – A vector function in 3D space that returns the magnetic field vector at any requested point.
composition (Composition) – The composition object manages all the atomic plasma species and provides access to their distribution functions.
electron_distribution (DistributionFunction) – A distribution function object describing the electron species properties.
geometry (Primitive) – The Raysect primitive that defines the geometric extent of this plasma.
geometry_transform (AffineMatrix3D) – The relative difference between the plasmas’ local coordinate system and the bounding geometries’ local coordinate system. Defaults to a Null transform.
models (ModelManager) – The manager class that sets and provides access to the emission models for this plasma.

>>> # This example shows how to initialise and populate a basic plasma
>>>
>>> from scipy.constants import atomic_mass, electron_mass
>>> from raysect.core.math import Vector3D
>>> from raysect.primitive import Sphere
>>> from raysect.optical import World
>>>
>>> from cherab.core import Plasma, Species, Maxwellian
>>> from cherab.core.atomic import deuterium
>>> from cherab.openadas import OpenADAS
>>>
>>>
>>> world = World()
>>>
>>> # create atomic data source
>>> adas = OpenADAS(permit_extrapolation=True)
>>>
>>>
>>> # Setup basic distribution functions for the species
>>> d0_density = 1E17
>>> d0_temperature = 1
>>> bulk_velocity = Vector3D(0, 0, 0)
>>> d0_distribution = Maxwellian(d0_density, d0_temperature, bulk_velocity, deuterium.atomic_weight * atomic_mass)
>>> d0_species = Species(deuterium, 0, d0_distribution)
>>>
>>> d1_density = 1E18
>>> d1_temperature = 10
>>> d1_distribution = Maxwellian(d1_density, d1_temperature, bulk_velocity, deuterium.atomic_weight * atomic_mass)
>>> d1_species = Species(deuterium, 1, d1_distribution)
>>>
>>> e_distribution = Maxwellian(1E18, 9.0, bulk_velocity, electron_mass)
>>>
>>> # Initialise Plasma object and populate with species specifications
>>> plasma = Plasma(parent=world)
>>> plasma.atomic_data = adas
>>> plasma.geometry = Sphere(2.0)
>>> plasma.b_field = Vector3D(1.0, 1.0, 1.0)
>>> plasma.composition = [d0_species, d1_species]
>>> plasma.electron_distribution = e_distribution

ion_density(x, y, z)¶

Calculates the total ion density of the plasma.

\[n_I = \sum_{k=1}^N n_i(k)\]

Parameters

x – x coordinate in meters.
y – y coordinate in meters.
z – z coordinate in meters.

Returns

Total ion density in m^-3.

>>> # With an already initialised plasma object...
>>> plasma.ion_density(1, 1, 1)
1.1e+18

z_effective(x, y, z)¶

Calculates the effective Z of the plasma.

\[Z_{eff} = \sum_{j=1}^N n_{i(j)} Z_j^2 / \sum_{k=1}^N n_{i(k)} Z_k\]

where n is the species density and Z is the ionisation of the species.

Parameters

x – x coordinate in meters.
y – y coordinate in meters.
z – z coordinate in meters.

Returns

Calculated Z effective.

Raises

ValueError – If plasma does not contain any ionised species.

>>> # With an already initialised plasma object...
>>> plasma.z_effective(1, 1, 1)
1.0

7.1.2. Plasma Species¶

class cherab.core.Species¶

A class representing a given plasma species.

A plasma in Cherab will be composed of 1 or more Species objects. A species can be uniquely identified through its element and charge state.

When instantiating a Species object a 6D distribution function (3 space, 3 velocity) must be defined. The DistributionFunction object provides the base interface for defining a distribution function, it could be a reduced analytic representation (such as a Maxwellian for example) or a fully numerically interpolated 6D function.

Parameters

element (Element) – The element object of this species.
charge (int) – The charge state of the species.
distribution (DistributionFunction) – A distribution function for this species.

>>> # In this example we define a single plasma species with spatially homogeneous properties
>>>
>>> from scipy.constants import atomic_mass
>>> from raysect.core.math import Vector3D
>>> from cherab.core import Species, Maxwellian
>>> from cherab.core.atomic import deuterium
>>>
>>> # Setup a distribution function for the species
>>> density = 1E18
>>> temperature = 10
>>> bulk_velocity = Vector3D(-1e6, 0, 0)
>>> d1_distribution = Maxwellian(density, temperature, bulk_velocity, deuterium.atomic_weight * atomic_mass)
>>>
>>> # create the plasma Species object
>>> d1_species = Species(deuterium, 1, d1_distribution)
>>>
>>> # Request some properties from the species' distribution function.
>>> print(d1_species)
<Species: element=deuterium, charge=1>
>>> d1_species.distribution.density(1, -2.5, 7)
1e+18

class cherab.core.plasma.node.Composition¶

The plasma composition manager.

Used to control the adding and removing of Species objects from the Plasma object. This is because there can only ever be one Species object instance for each plasma species of a given element and charge state. Users never instantiate this class directly. Its always used indirectly through an instantiated Plasma object.

__getitem__()¶

Species objects can be indexed with a tuple specifying their element and charge state.

>>> plasma.composition[(deuterium, 0)]
<Species: element=deuterium, charge=0>

__iter__()¶

Used to iterate over all the Species objects in the parent plasma.

>>> [species for species in plasma.composition]
[<Species: element=deuterium, charge=0>,
 <Species: element=deuterium, charge=1>]

add(species)¶

Adds a species to the plasma composition.

Replaces any existing species with the same element and charge state already in the composition.

Parameters: species (Species) – A Species object.

>>> d1_species = Species(deuterium, 1, d1_distribution)
>>> plasma.composition.add(d1_species)

clear()¶: Removes all Species object instances from the parent plasma.

get(element, charge)¶

Get a specified plasma species.

Raises a ValueError if the specified species is not found in the composition.

Parameters

element (Element) – The element object of the requested species.
charge (int) – The charge state of the requested species.

Returns

The requested Species object.

>>> plasma.composition.get(deuterium, 1)
<Species: element=deuterium, charge=1>

set(species)¶

Replaces the species in the composition with a new list of species.

If there are multiple species with the same element and charge state in the list, only the last species with that specification will be added to the composition.

Parameters: species (Species) – A list containing the new species.

>>> d0_species = Species(deuterium, 0, d0_distribution)
>>> d1_species = Species(deuterium, 1, d1_distribution)
>>> plasma.composition.set([d0_species, d1_species])
>>> [species for species in plasma.composition]
[<Species: element=deuterium, charge=0>,
 <Species: element=deuterium, charge=1>]

7.1.3. Distribution functions¶

class cherab.core.distribution.DistributionFunction¶

The distribution function base class.

All plasma Species objects are defined through distribution functions. This base class defines the core interface which is used by the rest of the framework. This base class cannot be used on its own, it raises a NotImplementedError() on all method calls. Users should either use a simpler distribution instance (such as the Maxwellian distribution) or implement their own.

__call__()¶

Evaluates the phase space density at the specified point in 6D phase space.

Wraps the cython evaluate() function for fast evaluation.

Parameters

x (float) – position in meters
y (float) – position in meters
z (float) – position in meters
vx (float) – velocity in meters per second
vy (float) – velocity in meters per second
vz (float) – velocity in meters per second

Returns

phase space density in s^3/m^6

bulk_velocity(x, y, z)¶

Evaluates the species’ bulk velocity at the specified 3D coordinate.

Parameters

x (float) – position in meters
y (float) – position in meters
z (float) – position in meters

Returns

velocity vector in m/s

Return type

Vector3D

density(x, y, z)¶

Evaluates the species’ density at the specified 3D coordinate.

Parameters

x (float) – position in meters
y (float) – position in meters
z (float) – position in meters

Returns

density in m^-3

Return type

float

effective_temperature(x, y, z)¶

Evaluates the species’ effective temperature at the specified 3D coordinate.

Parameters

x (float) – position in meters
y (float) – position in meters
z (float) – position in meters

Returns

temperature in eV

Return type

float

class cherab.core.distribution.Maxwellian¶

Bases: cherab.core.distribution.DistributionFunction

A Maxwellian distribution function.

This class implements a Maxwell-Boltzmann distribution, the statistical distribution describing a system of particles that have reached thermodynamic equilibrium. The user supplies 3D functions that provide the mean density, temperature and velocity respectively.

Parameters

density (Function3D) – 3D function defining the density in cubic meters.
temperature (Function3D) – 3D function defining the temperature in eV.
velocity (VectorFunction3D) – 3D vector function defining the bulk velocity in meters per second.
atomic_mass (double) – Atomic mass of the species in kg.

>>> from scipy.constants import atomic_mass
>>> from raysect.core.math import Vector3D
>>> from cherab.core import Maxwellian
>>> from cherab.core.atomic import deuterium
>>>
>>> # Setup distribution for a slab of plasma in thermodynamic equilibrium
>>> d0_density = 1E17
>>> d0_temperature = 1
>>> bulk_velocity = Vector3D(0, 0, 0)
>>> d0_distribution = Maxwellian(d0_density, d0_temperature, bulk_velocity, deuterium.atomic_weight * atomic_mass)

bulk_velocity(x, y, z)¶

Evaluates the species’ bulk velocity at the specified 3D coordinate.

Parameters

x – position in meters
y – position in meters
z – position in meters

Returns

velocity vector in m/s

>>> d0_distribution.bulk_velocity(1, 0, 0)
Vector3D(0.0, 0.0, 0.0)

density(x, y, z)¶

Parameters

x – position in meters
y – position in meters
z – position in meters

Returns

density in m^-3

>>> d0_distribution.density(1, 0, 0)
1e+17

effective_temperature(x, y, z)¶

Parameters

x – position in meters
y – position in meters
z – position in meters

Returns

temperature in eV

>>> d0_distribution.effective_temperature(1, 0, 0)
1.0