NcHarmonic

Single perturbation harmonic from a netCDF file of the form:

\[ \alpha_{\{m, n\}}(\psi/\psi_p) \cos\big(m\theta - n\zeta + \phi(\psi/\psi_p) \big) \]

where \(\alpha\) and \(\phi\) can be expressed as functions of either or both \(\psi, \psi_p\), and are calculated by interpolation over the numerical data.

dexter.NcHarmonic(path: str, interp_type: Interp1DType, m: int, n: int, phase_method: PhaseMethod = 'Zero', analytical_threshold_index: int = 3)

Single perturbation harmonic from a netCDF file.

Phase calculation configuration

\(\phi\) calculation can be further configured with the phase_method optional parameter, which defaults to Resonance, meaning that a constant value equal to the value of \(\phi\) at the resonance is used. If no valid value can be found, it falls back to Zero. See PhaseMethod) for available configurations.

Example

Phase calculation configuration

>>> harmonic = dex.NcHarmonic(path, "cubic", 3, 2, phase_method = "Average")
>>> harmonic = dex.NcHarmonic(path, "cubic", 3, 2, phase_method = "Interpolation")
>>> harmonic = dex.NcHarmonic(path, "cubic", 3, 2, phase_method = ("Custom", 3.1415))

Analytical patch

By definition, flute modes must behave like \(\sqrt\psi\) close to the axis, and therefore their derivative with respect to the flux must go to infinity. This is a behavior that splines cannot replicate, resulting to unnatural orbits close to the magnetic axis.

To solve this, the harmonic switches to an analytical formula for the values of \(\psi/\psi_p\) under a certain threshold. The threshold is defined by the flux value at the position analytical_threshold_index of the data array.

Formula

The patch has the form \(\beta\sqrt\psi + \gamma\), where \(\beta\) and \(\gamma\) are adjusted in order to ensure continuity of both $\alpha\psi and its first derivative. \(\beta\) is calculated first by \(\beta = 2\alpha'\sqrt\psi\) to ensure the correct value of the derivative \(\alpha'\) at the patch’s edge. Finally, \(\gamma = \alpha - \beta \sqrt\psi\) ensures the continuity of \(\alpha\) itself.

Note that sometimes \(\gamma\) may become slightly negative, resulting to \(\alpha\) becoming slightly negative extremely close to the axis. However this error should be negligible compared to the possible non-continuity of \(\alpha\)’s higher derivatives or its deviation from the actual data.

Parameters:

• path (str) –

  The path to the NetCDF file.

• interp_type (Interp1DType) –

  The type of 1D Interpolation.

• m (int) –

  The poloidal mode number \(m\).

• n (int) –

  The poloidal mode number \(n\).

• phase_method (PhaseMethod, default: 'Zero' ) –

  The method of calculation of the phase \(\phi(\psi/\psi_p)\). Defaults to "Resonance".

• analytical_threshold_index (int, default: 3 ) –

  The harmonic’s analytical threshold point. See Note. Defaults to 3.

Methods:

• alpha_of_psi –

  The harmonic's amplitude \(\alpha(\psi, \theta, \zeta, t)\) value in Normalized Units.

• alpha_of_psip –

  The harmonic's amplitude \(\alpha(\psi_p, \theta, \zeta, t)\) value in Normalized Units.

• phase_of_psi –

  The harmonic's phase \(\phi(\psi, \theta, \zeta, t)\) value in Normalized Units.

• phase_of_psip –

  The harmonic's phase \(\phi(\psi_p, \theta, \zeta, t)\) value in Normalized Units.

• plot_alpha_of_psi –

  Plots the harmonic's amplitude \(\alpha(\psi)\).

• plot_alpha_of_psip –

  Plots the harmonic's amplitude \(\alpha(\psi_p)\).

• plot_phase_of_psi –

  Plots the harmonic's phase \(\phi(\psi)\).

• plot_phase_of_psip –

  Plots the harmonic's phase \(\phi(\psi_p)\).

• plot_dalpha_of_psi –

  Plots the harmonic's amplitude's deritave \(d\alpha(\psi)/d\psi\).

• plot_dalpha_of_psip –

  Plots the harmonic's amplitude's deritave \(d\alpha(\psi_p)/d\psi_p\).

• h_of_psi –

  The full harmonic's value \(h(\psi, \theta, \zeta, t)\) value in Normalized Units.

• h_of_psip –

  The full harmonic's value \(h(\psi_p, \theta, \zeta, t)\) value in Normalized Units.

• dh_dpsi –

  The harmonic's derivative with respect to \(\psi\), \(\partial h(\psi, \theta, \zeta, t)/\partial\psi\)

• dh_dpsip –

  The harmonic's derivative with respect to \(\psi_p\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial \psi_p\)

• dh_of_psi_dtheta –

  The harmonic's derivative with respect to \(\theta\), \(\partial h(\psi, \theta, \zeta, t)/\partial \theta\)

• dh_of_psip_dtheta –

  The harmonic's derivative with respect to \(\theta\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial \theta\)

• dh_of_psi_dzeta –

  The harmonic's derivative with respect to \(\zeta\), \(\partial h(\psi, \theta, \zeta, t)/\partial \zeta\)

• dh_of_psip_dzeta –

  The harmonic's derivative with respect to \(\zeta\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial \zeta\)

• dh_of_psi_dt –

  The harmonic's derivative with respect to the time \(t\), \(\partial h(\psi, \theta, \zeta, t)/\partial t\)

• dh_of_psip_dt –

  The harmonic's derivative with respect to the time \(t\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial t\)

Attributes:

• psi_state (FluxState) –

  The state of the toroidal flux coordinate.

• psip_state (FluxState) –

  The state of the poloidal flux coordinate.

• path (str) –

  The path of the netCDF file.

• netcdf_version (NetCDFVersion) –

  The netCDF convention version (SemVer).

• equilibrium_type (EquilibriumType) –

  The object's equilibrium's type.

• interp_type (str) –

  The Interpolation type.

• m (int) –

  The harmonic's poloidal mode number \(m\).

• n (int) –

  The harmonic's toroidal mode number \(n\).

• phase_method (PhaseMethod) –

  The method of calculation of the phase \(\phi(\psi/\psi_p)\).

• phase_average (float) –

  The average value of the phase arrays, if phase_method is Average.

• psi_phase_resonance (float) –

  The toroidal flux’s value where the resonance is met, if phase_method is Resonance and

• psip_phase_resonance (float) –

  The poloidal flux’s value where the resonance is met, if phase_method is Resonance and

• analytical_threshold_index (float) –

  The harmonic’s analytical threshold point.

• psi_last (float) –

  The value of the last closed toroidal flux surface \(\psi_{LCFS}\) in Normalized Units.

• psip_last (float) –

  The value of the last closed poloidal flux surface \(\psi_{p,LCFS}\) in Normalized Units.

• psi_array (Array1) –

  The NetCDF \(\psi\) data.

• psip_array (Array1) –

  The NetCDF \(\psi_p\) data.

• alpha_array (Array1) –

  The NetCDF \(\alpha\) data.

• phase_array (Array1) –

  The NetCDF \(\phi\) data.

dexter.NcHarmonic.psi_state: FluxState property

The state of the toroidal flux coordinate.

dexter.NcHarmonic.psip_state: FluxState property

The state of the poloidal flux coordinate.

dexter.NcHarmonic.path: str property

The path of the netCDF file.

dexter.NcHarmonic.netcdf_version: NetCDFVersion property

The netCDF convention version (SemVer).

dexter.NcHarmonic.equilibrium_type: EquilibriumType property

The object's equilibrium's type.

dexter.NcHarmonic.interp_type: str property

The Interpolation type.

dexter.NcHarmonic.m: int property

The harmonic's poloidal mode number \(m\).

dexter.NcHarmonic.n: int property

The harmonic's toroidal mode number \(n\).

dexter.NcHarmonic.phase_method: PhaseMethod property

The method of calculation of the phase \(\phi(\psi/\psi_p)\).

dexter.NcHarmonic.phase_average: float property

The average value of the phase arrays, if phase_method is Average.

dexter.NcHarmonic.psi_phase_resonance: float property

The toroidal flux’s value where the resonance is met, if phase_method is Resonance and the resonance is in bounds.

dexter.NcHarmonic.psip_phase_resonance: float property

The poloidal flux’s value where the resonance is met, if phase_method is Resonance and the resonance is in bounds.

dexter.NcHarmonic.analytical_threshold_index: float property

The harmonic’s analytical threshold point.

dexter.NcHarmonic.psi_last: float property

The value of the last closed toroidal flux surface \(\psi_{LCFS}\) in Normalized Units.

dexter.NcHarmonic.psip_last: float property

The value of the last closed poloidal flux surface \(\psi_{p,LCFS}\) in Normalized Units.

dexter.NcHarmonic.psi_array: Array1 property

The NetCDF \(\psi\) data.

dexter.NcHarmonic.psip_array: Array1 property

The NetCDF \(\psi_p\) data.

dexter.NcHarmonic.alpha_array: Array1 property

The NetCDF \(\alpha\) data.

dexter.NcHarmonic.phase_array: Array1 property

The NetCDF \(\phi\) data.

dexter.NcHarmonic.alpha_of_psi(psi: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's amplitude \(\alpha(\psi, \theta, \zeta, t)\) value in Normalized Units.

Parameters:

• psi (ArrayLike) –

  The toroidal flux \(\psi\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.alpha_of_psip(psip: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's amplitude \(\alpha(\psi_p, \theta, \zeta, t)\) value in Normalized Units.

Parameters:

• psip (ArrayLike) –

  The poloidal flux \(\psi_p\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.phase_of_psi(psi: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's phase \(\phi(\psi, \theta, \zeta, t)\) value in Normalized Units.

Parameters:

• psi (ArrayLike) –

  The toroidal flux \(\psi\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.phase_of_psip(psip: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's phase \(\phi(\psi_p, \theta, \zeta, t)\) value in Normalized Units.

Parameters:

• psip (ArrayLike) –

  The poloidal flux \(\psi_p\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.plot_alpha_of_psi(points: int = 1000, data: bool = False, show: bool = True) -> Canvas

Plots the harmonic's amplitude \(\alpha(\psi)\).

Note

It is assumed that the amplitude \(\alpha\) is only a function of the flux.

Parameters:

• points (int, default: 1000 ) –

  The number of points in which to evaluate \(\alpha(\psi)\). Defaults to 1000.

• data (bool, default: False ) –

  Whether or not to plot the data array points (numerical equilibria only). Defaults to False.

• show (bool, default: True ) –

  Whether or not to call plt.show(). Defaults to True.

Returns:

• Canvas –

  The produced Figure and Ax.

dexter.NcHarmonic.plot_alpha_of_psip(points: int = 1000, data: bool = False, show: bool = True) -> Canvas

Plots the harmonic's amplitude \(\alpha(\psi_p)\).

Note

It is assumed that the amplitude \(\alpha\) is only a function of the flux.

Parameters:

• points (int, default: 1000 ) –

  The number of points in which to evaluate \(\alpha(\psi_p)\). Defaults to 1000.

• data (bool, default: False ) –

  Whether or not to plot the data array points (numerical equilibria only). Defaults to False.

• show (bool, default: True ) –

  Whether or not to call plt.show(). Defaults to True.

Returns:

• Canvas –

  The produced Figure and Ax.

dexter.NcHarmonic.plot_phase_of_psi(points: int = 1000, data: bool = False, resonance: bool = True, show: bool = True) -> Canvas

Plots the harmonic's phase \(\phi(\psi)\).

Note

It is assumed that the amplitude \(\phi\) is only a function of the flux.

Parameters:

• points (int, default: 1000 ) –

  The number of points in which to evaluate \(\phi(\psi)\). Defaults to 1000.

• data (bool, default: False ) –

  Whether or not to plot the data array points (numerical equilibria only). Defaults to False.

• resonance (bool, default: True ) –

  Whether or not to plot the resonance location, if phase_method is Resonance. Defaults to True.

• show (bool, default: True ) –

  Whether or not to call plt.show(). Defaults to True.

Returns:

• Canvas –

  The produced Figure and Ax.

dexter.NcHarmonic.plot_phase_of_psip(points: int = 1000, data: bool = False, resonance: bool = True, show: bool = True) -> Canvas

Plots the harmonic's phase \(\phi(\psi_p)\).

Note

It is assumed that the amplitude \(\phi\) is only a function of the flux.

Parameters:

• points (int, default: 1000 ) –

  The number of points in which to evaluate \(\phi(\psi_p)\). Defaults to 1000.

• data (bool, default: False ) –

  Whether or not to plot the data array points (numerical equilibria only). Defaults to False.

• resonance (bool, default: True ) –

  Whether or not to plot the resonance location, if phase_method is Resonance. Defaults to True.

• show (bool, default: True ) –

  Whether or not to call plt.show(). Defaults to True.

Returns:

• Canvas –

  The produced Figure and Ax.

dexter.NcHarmonic.plot_dalpha_of_psi(points: int = 1000, show: bool = True) -> Canvas

Plots the harmonic's amplitude's deritave \(d\alpha(\psi)/d\psi\).

Note

It is assumed that the amplitude \(\alpha\) is only a function of the flux.

Parameters:

• points (int, default: 1000 ) –

  The number of points in which to evaluate \(d\alpha(\psi)/d\psi\). Defaults to 1000.

• show (bool, default: True ) –

  Whether or not to call plt.show(). Defaults to True.

Returns:

• Canvas –

  The produced Figure and Ax.

dexter.NcHarmonic.plot_dalpha_of_psip(points: int = 1000, show: bool = True) -> Canvas

Plots the harmonic's amplitude's deritave \(d\alpha(\psi_p)/d\psi_p\).

Note

It is assumed that the amplitude \(\alpha\) is only a function of the flux.

Parameters:

• points (int, default: 1000 ) –

  The number of points in which to evaluate \(d\alpha(\psi_p)/d\psi_p\). Defaults to 1000.

• show (bool, default: True ) –

  Whether or not to call plt.show(). Defaults to True.

Returns:

• Canvas –

  The produced Figure and Ax.

dexter.NcHarmonic.h_of_psi(psi: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The full harmonic's value \(h(\psi, \theta, \zeta, t)\) value in Normalized Units.

Parameters:

• psi (ArrayLike) –

  The toroidal flux \(\psi\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.h_of_psip(psip: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The full harmonic's value \(h(\psi_p, \theta, \zeta, t)\) value in Normalized Units.

Parameters:

• psip (ArrayLike) –

  The poloidal flux \(\psi_p\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_dpsi(psi: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to \(\psi\), \(\partial h(\psi, \theta, \zeta, t)/\partial\psi\) in Normalized Units.

Parameters:

• psi (ArrayLike) –

  The toroidal flux \(\psi\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_dpsip(psip: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to \(\psi_p\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial \psi_p\) in Normalized Units.

Parameters:

• psip (ArrayLike) –

  The poloidal flux \(\psi_p\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_of_psi_dtheta(psi: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to \(\theta\), \(\partial h(\psi, \theta, \zeta, t)/\partial \theta\) in Normalized Units, as a function of \(\psi\).

Parameters:

• psi (ArrayLike) –

  The toroidal flux \(\psi\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_of_psip_dtheta(psip: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to \(\theta\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial \theta\) in Normalized Units, as a function of \(\psi_p\).

Parameters:

• psip (ArrayLike) –

  The poloidal flux \(\psi_p\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_of_psi_dzeta(psi: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to \(\zeta\), \(\partial h(\psi, \theta, \zeta, t)/\partial \zeta\) in Normalized Units, as a function of \(\psi\).

Parameters:

• psi (ArrayLike) –

  The toroidal flux \(\psi\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_of_psip_dzeta(psip: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to \(\zeta\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial \zeta\) in Normalized Units, as a function of \(\psi_p\).

Parameters:

• psip (ArrayLike) –

  The poloidal flux \(\psi_p\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_of_psi_dt(psi: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to the time \(t\), \(\partial h(\psi, \theta, \zeta, t)/\partial t\) in Normalized Units, as a function of \(\psi\).

Parameters:

• psi (ArrayLike) –

  The toroidal flux \(\psi\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units

dexter.NcHarmonic.dh_of_psip_dt(psip: ArrayLike, theta: ArrayLike, zeta: ArrayLike, t: ArrayLike) -> NDArray

The harmonic's derivative with respect to the time \(t\), \(\partial h(\psi_p, \theta, \zeta, t)/\partial t\) in Normalized Units, as a function of \(\psi_p\).

Parameters:

• psip (ArrayLike) –

  The poloidal flux \(\psi_p\) in Normalized Units.

• theta (ArrayLike) –

  The \(\theta\) angle in \([rads]\).

• zeta (ArrayLike) –

  The \(\zeta\) angle in \([rads]\).

• t (ArrayLike) –

  The time in Normalized Units