gvec.core.state#

gvec.state - low-level python API for postprocessing

The gvec.state module provides the State class which wraps the src/pygvec/state.f90 fortran module. It provides an encapsulation for the state of the GVEC library, allowing safe postprocessing routines. This module checks the input arguments and handles the initialization and finalization of the Fortran state.

  1. gvec library - src/*

  2. fortran API - src/pygvec/*

    • 1 & 2 are compiled into the gveclib (static) library

  3. fortran wrapping layer - f90wrap_* - autogenerated by f90wrap

  4. C wrapping layer - _libpygvecmodule.c - autogenerated by f2py

    • 3 & 4 are compiled into the _libpygvec* shared library which can be imported in python

  5. python wrapping layer - lib.py - autogenerated by f90wrap

  6. low-level python API - state.py

    • ensures safe access to the underlying layers

  7. high-level python API - comp.py, run.py

class gvec.core.state.State(parameterfile: str | Path, statefile: str | Path | None = None)#

Bases: object

A class for encapsulating the ‘state’ of the GVEC library with all relevant parameters and variables.

bind()#

Bind this State object to the Fortran library. Allocate & initialize everything.

compute(ev: Dataset, *quantities: str)#
evaluate(*quantities: str, rho: Literal['int'] | int | float | DataArray | ndarray | Sequence | None = 'int', theta: Literal['int'] | int | float | DataArray | ndarray | Sequence | None = 'int', zeta: Literal['int'] | int | float | DataArray | ndarray | Sequence | None = 'int')#
evaluate_base_list_rtz_all(quantity: str, rhothetazeta: ndarray)#
evaluate_base_list_tz(quantity: str, derivs: str | None, rho: ndarray, thetazeta: ndarray)#
evaluate_base_list_tz_all(quantity: str, rho: ndarray, thetazeta: ndarray)#
evaluate_base_tens(quantity: str, derivs: str | None, rho: ndarray, theta: ndarray, zeta: ndarray)#
evaluate_base_tens_all(quantity: str, rho: ndarray, theta: ndarray, zeta: ndarray)#
evaluate_boozer_list_tz_all(sfl_boozer: t_sfl_boozer, quantity: str, rad: ndarray, thetazeta: ndarray)#
evaluate_hmap(X1: ndarray, X2: ndarray, zeta: ndarray, dX1_dr: ndarray, dX2_dr: ndarray, dX1_dt: ndarray, dX2_dt: ndarray, dX1_dz: ndarray, dX2_dz: ndarray) → tuple[ndarray, ndarray, ndarray, ndarray]#
evaluate_hmap_only(X1: ndarray, X2: ndarray, zeta: ndarray) → tuple[ndarray, ndarray, ndarray, ndarray]#
evaluate_jac_h_derivs(X1: ndarray, X2: ndarray, zeta: ndarray, dX1_dr: ndarray, dX2_dr: ndarray, dX1_dt: ndarray, dX2_dt: ndarray, dX1_dz: ndarray, dX2_dz: ndarray) → tuple[ndarray, ndarray, ndarray]#
evaluate_metric_derivs(X1: ndarray, X2: ndarray, zeta: ndarray, dX1_dr: ndarray, dX2_dr: ndarray, dX1_dt: ndarray, dX2_dt: ndarray, dX1_dz: ndarray, dX2_dz: ndarray, dX1_drr: ndarray, dX2_drr: ndarray, dX1_drt: ndarray, dX2_drt: ndarray, dX1_drz: ndarray, dX2_drz: ndarray, dX1_dtt: ndarray, dX2_dtt: ndarray, dX1_dtz: ndarray, dX2_dtz: ndarray, dX1_dzz: ndarray, dX2_dzz: ndarray) → tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]#
evaluate_profile(quantity: str, rho: ndarray, deriv: int = 0)#

Evaluate 1D profiles at the provided positions of the radial coordinate rho.

Parameters:

  • quantity (str) – name of the profile. Has to be either iota (rotational transform), p (pressure), `chi`(poloidal magn. flux), `Phi`(toroidal magn. flux)

  • rho (np.ndarray) – Positions at the radial flux coordinate rho.

  • deriv (int, optional) – Order of the derivative in rho. Note that for some quantities not all derivatives can be calculated, e.g. for iota and p the maximum is deriv=4. Defaults to 0.

Raises:

  • ValueError – If `quantity`is not a string.

  • ValueError – If an invalid quantity is provided.

  • NotImplementedError – If deriv > 1 for quantity=”chi”.

  • ValueError – If rho is not a 1D array.

  • ValueError – If rho is not in [0, 1].

Returns:

profile values at rho.

Return type:

np.ndarray

evaluate_rho2_profile(quantity: str, rho2: ndarray, deriv: int = 0)#

Evaluate 1D profiles at the provided positions of the radial coordinate rho2`=:math:rho^2`. Note: Use this routine to obtain derivarives with respect to rho2, else use evaluate_profile.

Parameters:

  • quantity (str) – name of the profile. Has to be either iota or p

  • rho2 (np.ndarray) – Positions at the radial flux coordinate rho^2.

  • deriv (int, optional) – Order of the derivative, in s=rho^2 (!). Defaults to 0.

Raises:

  • ValueError – If `quantity`is not a string.

  • ValueError – If an invalid quantity is provided.

  • ValueError – If rho2 is not a 1D array.

  • ValueError – If rho2 is not in [0, 1].

Returns:

profile values at rho2.

Return type:

np.ndarray

evaluate_sfl(*quantities: str, rho: Literal['int'] | int | float | DataArray | ndarray | Sequence | None = 'int', theta: Literal['int'] | int | float | DataArray | ndarray | Sequence | None = 'int', zeta: Literal['int'] | int | float | DataArray | ndarray | Sequence | None = 'int', sfl: Literal['boozer', 'pest'] = 'boozer', **boozer_kwargs)#
get_boozer(rho: ndarray, MNfactor: int = 5, *, M: int | None = None, N: int | None = None, M_nyq: int | None = None, N_nyq: int | None = None, sincos: Literal['sin', 'cos', 'sincos'] = 'sin', recompute_lambda: bool = True)#

Initialize a new Boozer potential with M poloidal and N toroidal nodes for all fluxsurfaces given by rho.

Parameters:

  • rho – Array of (radius-like) flux surface labels.

  • MNfactor – Multiplication factor between the maximum M, N of the equilbrium and the maximum M, N of the Boozer potential. Only used if M, N are not explicitly given.

  • M – Number of poloidal nodes of the Boozer potential \(\nu_B\). Defaults to the maximum number of nodes of the basis.

  • N – Number of toroidal nodes of the Boozer potential \(\nu_B\). Defaults to the maximum number of nodes of the basis.

Returns:

Straight-fieldline Boozer object (wrapped Fortran object).

Return type:

sfl_boozer

get_boozer_angles(sfl_boozer: t_sfl_boozer, tz_list: ndarray, rad: int | None = None)#

Find the logical angles (theta, zeta) for the corresponding (theta_B, zeta_B) coordinates on the Boozer surface.

Parameters:

  • sfl_boozer (lib.Modgvec_Sfl_Boozer.t_sfl_boozer) – The Boozer potential object to use.

  • tz_list (2D array or Sequence of shape (2, n)) – The list of (theta_B, zeta_B) coordinates for which to find the logical angles. The first row contains theta_B and the second row contains zeta_B.

  • rad (int, optional) – The (optional) radial index of the surface (with respect to the sfl_boozer object) on which to find the angles.

Returns:

The logical angles (theta, zeta) corresponding to the input (theta_B, zeta_B) coordinates. If rad is None, returns a 3D array of shape (2, n, nrho), where nrho is the number of radial surfaces in sfl_boozer. If rad is specified, returns a 2D array of shape (2, n).

Return type:

2D or 3D np.ndarray

get_integration_points(quantity: str = 'LA')#
get_mn_max(quantity: str = 'all') → tuple[int, int]#
classmethod new(parameters: Mapping, rundir: str | Path | None = None)#
property nfp#
property rundir#
property stdout: str#
unbind()#

Unbind this State object from the Fortran library. Finalize & deallocate everything.

gvec.core.state.find_state(rundir: str | Path | None = None)#

Load a State object from a given run-directory. Use the latest statefile which is found.

gvec.core.state.find_states(rundir: str | Path | None = None)#

Load a Sequence of State objects from a given run-directory.

gvec.core.state.load_state(parameterfile: Path | str, statefile: Path | str)#

Load a State object from a given parameterfile (.ini) and statefile (.dat).