Skip to content

Particle

dexter.Particle(initial_conditions: InitialConditions)

A Particle.

By taking $\mu = 0$ and $\rho \rightarrow 0$, the particle traces magnetic field lines.

Parameters:

Example

Particle creation from a Boozer Coordinates set
>>> initial_conditions = dex.InitialConditions.Boozer(
...     t0=0,
...     flux0=dex.MagneticFlux.Toroidal(0.1),
...     theta0=3.14,
...     zeta0=0,
...     rho0=1e-4,
...     mu0=7e-6,
... )
>>> particle = dex.Particle(initial_conditions)
Particle creation from a Mixed Coordinates set
>>> initial_conditions = dex.InitialConditions.Mixed(
...     t0=0,
...     flux0=dex.MagneticFlux.Poloidal(0.1),
...     theta0=3.14,
...     zeta0=0,
...     pzeta0=-0.025,
...     mu0=7e-6,
... )
>>> particle = dex.Particle(initial_conditions)

Attributes:

  • initial_conditions (InitialConditions) –

    The Particle's InitialConditions set.

  • integration_status (IntegrationStatus) –

    The Particle's IntegrationStatus.

  • steps_taken (int) –

    The total number of steps taken during the integration. This number is not necessarily the same as the number of steps stored.

  • steps_stored (int) –

    The total number of steps stored in the time series arrays.

  • duration (str) –

    The duration of the integration routine.

  • initial_energy (float) –

    The Particle's initial energy in Normalized Units.

  • final_energy (float) –

    The Particle's final energy in Normalized Units.

  • energy_rsd (float) –

    The relative standard deviation of the particles energy_array. It is defined as $\sigma/\mu$, where $\sigma$ the standard deviation and $\mu$ the mean energy value.

  • energy_pzeta_position (EnergyPzetaPosition) –

    The Particle's EnergyPzetaPosition.

  • orbit_type (OrbitType) –

    The Particle's OrbitType.

  • omega_theta (float) –

    The Particle's $\omega_\theta$ frequency in Normalized Units.

  • omega_zeta (float) –

    The Particle's $\omega_\zeta$ frequency in Normalized Units.

  • qkinetic (float) –

    The Particle's $q_{kinetic}$.

  • flux_cache_hits (int) –

    The magnetic flux' Accelerator cache hits.

  • flux_cache_misses (int) –

    The magnetic flux' Accelerator cache misses.

  • theta_cache_hits (int) –

    The $\theta$ coordinate's Accelerator cache misses.

  • theta_cache_misses (int) –

    The $\theta$ coordinate's Accelerator cache misses.

  • mode_cache_hits (int) –

    The modes' Accelerator cache hits.

  • mode_cache_misses (int) –

    The modes' Accelerator cache misses.

  • t_array (Array1) –

    The $t$ array.

  • psit_array (Array1) –

    The $\psi_t$ array.

  • psip_array (Array1) –

    The $\psi_p$ array.

  • theta_array (Array1) –

    The $\theta$ array.

  • zeta_array (Array1) –

    The $\zeta$ array.

  • rho_array (Array1) –

    The $\rho_{||}$ array.

  • mu_array (Array1) –

    The $\mu$ array.

  • ptheta_array (Array1) –

    The $P_\theta$ array.

  • pzeta_array (Array1) –

    The $P_\zeta$ array.

  • energy_array (Array1) –

    The energy array.

FromCriticalPoint(point: CriticalPoint) -> Particle classmethod

Crates a particle with initial conditions on a CriticalPoint.

This is useful for inspecting the critical points calculated from a bifurcation analysis.

Note

The particle's $t_0$ and $\zeta_0$ are set to $0$.

integrate(machine: Machine, teval: tuple[float, float], solver_params: SolverParams | None = None)

Integrates the particle for a specific time interval.

The time interval is in Normalized Units (inverse gyro-frequency).

Parameters:

  • machine (Machine) –

    The machine in which to integrate the particle.

  • teval (tuple[float, float]) –

    The time span $(t_0, t_f)$ in which to integrate the particle, in Normalized Units.

  • solver_params (SolverParams | None, default: None ) –

    The parameters passed to the solver.

Example
Particle integration
>>> # Machine setup
>>> LCFS = dex.MagneticFlux.Toroidal(0.45)
>>> machine = dex.Machine(
...     qfactor=dex.ParabolicQfactor(qaxis=1.1, qlast=4.1, lcfs=LCFS),
...     current=dex.LarCurrent(),
...     bfield=dex.LarBfield(),
...     perturbation=dex.Perturbation(
...         [
...             dex.FluteMode(epsilon=1e-3, lcfs=LCFS, m=1, n=3, phase=0),
...             dex.FluteMode(epsilon=1e-3, lcfs=LCFS, m=2, n=3, phase=0),
...         ]
...     )
... )
>>>
>>> # Initial conditions setup
>>> initial_conditions = dex.InitialConditions.Boozer(
...     t0=0,
...     flux0=dex.MagneticFlux.Toroidal(0.1),
...     theta0=3.14,
...     zeta0=0,
...     rho0=1e-4,
...     mu0=7e-6,
... )
>>>
>>> # Particle setup and integration
>>> particle = dex.Particle(initial_conditions)
>>>
>>> solver_params = dex.SolverParams(
...     method=dex.SteppingMethod.EnergyAdaptiveStep(rel_tol=1e-7, abs_tol=1e-9),
...     max_steps=100_000,
... )
>>> particle.integrate(machine, teval=(0, 1e2), solver_params=solver_params)

intersect(machine: Machine, intersect_params: IntersectParams, solver_params: SolverParams | None = None)

Integrates the particle, calculating its intersections with a constant $\theta$ or $\zeta$ surface.

Using the method described by Hénon we can force the solver to step exactly on the intersection surface.

The differences between two consecutive values of the corresponding angle variable are guaranteed to be $2\pi \pm \epsilon$ or $0 \pm \epsilon$, where $\epsilon$ a number smaller than the solver’s relative tolerance.

Parameters:

  • machine (Machine) –

    The machine in which to integrate the particle.

  • intersect_params (IntersectParams) –

    The intersection parameters.

  • solver_params (SolverParams | None, default: None ) –

    The parameters passed to the solver.

Example
Particle intersection integration
>>> # Machine setup
>>> LCFS = dex.MagneticFlux.Toroidal(0.45)
>>> machine = dex.Machine(
...     qfactor=dex.ParabolicQfactor(qaxis=1.1, qlast=4.1, lcfs=LCFS),
...     current=dex.LarCurrent(),
...     bfield=dex.LarBfield(),
...     perturbation=dex.Perturbation(
...         [
...             dex.FluteMode(epsilon=1e-3, lcfs=LCFS, m=1, n=3, phase=0),
...             dex.FluteMode(epsilon=1e-3, lcfs=LCFS, m=2, n=3, phase=0),
...         ]
...     )
... )
>>>
>>> # Initial conditions and Intersection Parameters setup
>>> initial_conditions = dex.InitialConditions.Boozer(
...     t0=0,
...     flux0=dex.MagneticFlux.Toroidal(0.3),
...     theta0=3.14,
...     zeta0=0,
...     rho0=1e-3,
...     mu0=7e-5,
... )
>>>
>>> # Particle setup and intersection
>>> particle = dex.Particle(initial_conditions)
>>>
>>> intersect_params = dex.IntersectParams("ConstZeta", angle=3.1415, turns=5)
>>> particle.intersect(machine, intersect_params)

close(machine: Machine, periods: int = 1, solver_params: SolverParams | None = None)

Integrates the particle for a certain amount of $\theta-\psi$ periods.

When the particle approximately reaches its initial point after periods periods, it halts its integration and performs one more step using Hénon's trick, to land itself on the initial point exactly, similar to how [Particle.intersect] lands exactly on the intersection surface.

This routine also yields the particle's $\omega_theta$, $\omega_\zeta$ and $q_{kin}$.

This routine only uses the axisymmetric system, ignoring the Perturbation.

Parameters:

  • machine (Machine) –

    The machine in which to integrate the particle.

  • periods (int, default: 1 ) –

    The amount of periods to integrate.

  • solver_params (SolverParams | None, default: None ) –

    The parameters passed to the solver.

Example
Particle orbit closing
>>> # Machine setup
>>> LCFS = dex.MagneticFlux.Toroidal(0.45)
>>> machine = dex.Machine(
...     qfactor=dex.ParabolicQfactor(qaxis=1.1, qlast=4.1, lcfs=LCFS),
...     current=dex.LarCurrent(),
...     bfield=dex.LarBfield(),
... )
>>>
>>> # Initial conditions setup
>>> initial_conditions = dex.InitialConditions.Boozer(
...     t0=0,
...     flux0=dex.MagneticFlux.Toroidal(0.1),
...     theta0=3.14,
...     zeta0=0,
...     rho0=1e-5,
...     mu0=7e-6,
... )
>>>
>>> # Particle setup and integration
>>> particle = dex.Particle(initial_conditions)
>>> particle.close(machine)

classify(machine: Machine)

Classifies the particle’s orbit using its position on the $(E, P_\zeta, \mu=const)$ plane without integrating.

Note

This method follows R. B. White's rules for classifying orbits. it only works for up-down symmetric equilibria with radial electric field.

See the "$E-P_\zeta$ Positions" section on the Diagrams tab for explanation.

Parameters:

  • machine (Machine) –

    The machine in which to classify the particle.

Example
Particle classification
>>> # Machine setup
>>> LCFS = dex.MagneticFlux.Toroidal(0.45)
>>> machine = dex.Machine(
...     qfactor=dex.ParabolicQfactor(qaxis=1.1, qlast=4.1, lcfs=LCFS),
...     current=dex.LarCurrent(),
...     bfield=dex.LarBfield(),
... )
>>>
>>> # Initial conditions setup
>>> initial_conditions = dex.InitialConditions.Boozer(
...     t0=0,
...     flux0=dex.MagneticFlux.Toroidal(0.1),
...     theta0=3.14,
...     zeta0=0,
...     rho0=1e-4,
...     mu0=7e-6,
... )
>>>
>>> # Particle setup and classification
>>> particle = dex.Particle(initial_conditions)
>>> particle.classify(machine)

plot_evolution(machine: Machine, **kwargs: Any)

Wrapper around dexter.plot_evolution.

Parameters:

  • machine (Machine) –

    The machine in which the particle was integrated. It is used to convert specific quantities to SI units.

  • **kwargs (Any, default: {} ) –

    Extra arguments passed to dexter.plot_evolution.

plot_poloidal_drift(machine: Machine, **kwargs: Any)

Wrapper around dexter.plot_poloidal_drift.

Parameters: