ascotpy

Python interface to libascot.so.

class a5py.ascotpy.Ascotpy

Class with methods to initialize and access the data via Python.

This class will be inherited by Ascot class. Here we hide all the dirty implementation of the libascot.so interface in private methods and attributes so that the Ascot front is clean for the users.

Attributes:

_sim

Simulation offload data struct.

_offload_ready

Flag indicating if inputs are packed.

_nmrk

Number of markers currently in the marker array.

_inistate

Marker input array for interactive simulations.

_endstate

Marker output array for interactive simulations.

_diag_occupied

Flag indicating if diagnostics array contains data.

_diag_offload_array

Diagnostics data offload array.

_offload_array

Offload array containing the input data when this instance is packed.

_int_offload_array

Offload array for integers containing the input data when this instance is packed.

_bfield_offload_array

Offload data for the magnetic field input.

_efield_offload_array

Offload data for the electric field input.

_plasma_offload_array

Offload data for the plasma input.

_neutral_offload_array

Offload data for the neutral input.

_wall_offload_array

Offload data for the wall (float) input.

_wall_int_offload_array

Offload data for the wall (int) input.

_boozer_offload_array

Offload data for the Boozer input.

_mhd_offload_array

Offload data for the MHD input.

_asigma_offload_array

Offload data for the atomic data input.

_nbi_offload_array

Offload data for the neutral beam injector data input.

_mute

Mute output from libascot.so: “yes” - stdout and stderr both muted, “no” - output is not muted, “err” - stderr is printed.

DUMMY_QID = b''

Flag to use in _sim.qid_* to indicate that the input is not initialized.

get_plasmaquantities()

Return species present in plasma input.

input_eval(r, phi, z, t, *qnt, grid=False)

Evaluate input quantities at given coordinates.

This method uses ASCOT5 C-routines for evaluating inputs exactly as they are evaluated during a simulation. See input_eval_list() for a complete list of available input and derived quantities.

Parameters:

rarray_like

R coordinates where data is evaluated.

phiarray_like

phi coordinates where data is evaluated.

zarray_like

z coordinates where data is evaluated.

tarray_like

Time coordinates where data is evaluated.

*qntstr

Names of evaluated quantities.

gridbool, optional

Treat input coordinates as abscissae and return the evaluated quantities on a grid instead.

Returns:

valarray_like (n,) or (nr,nphi,nz,nt)

Quantity evaluated in each queried point.

NaN is returned at those points where the evaluation failed.

4D matrix is returned when grid=``True``.

Raises:

AssertionError

If required data has not been initialized.

RuntimeError

If evaluation in libascot.so failed.

input_eval_list(show=True)

Return quantities that can be evaluated from inputs.

The returned quantities are those that can be evaluated from the inputs with input_eval method. Units are not listed as that function returns quantities with units included.

The number ion species in plasma input is not fixed so “ni” refers to i’th plasma species as listed by input_getplasmaspecies (index starts from 1).

Parameters:

showbool, optional

Print output.

Returns:

quantitiesdict [str, str]

Name of each quantity and a short description.

input_eval_orbitresonance(rhogrid, xigrid, egrid, species, plot=False, n=1, p=0, omega=0.0, axes=None, cax=None)

Evaluate the resonance condition between particles and perturbations.

Orbit resonance refers to the phenomenon where the frequency of a particle’s orbit in a magnetic field matches the frequency of a perturbation, such as a wave or an external perturbation. This resonance can lead to increased particle transport.

The resonance condition for orbit resonance is given by:

f_{tor} / f_{pol} = m / n

where: - f_{tor} is the toroidal orbit frequency of the particle, - f_{pol} is the poloidal orbit frequency of the particle, - n is the toroidal mode number of the perturbation. - m is an arbitrary integer.

This function can evaluate and plot the resonance in 1D or 2D space. Note that one of the (‘rhogrid’, ‘xigrid’, ‘egrid’) must be a scalar.

Parameters:

rhogridarray_like, (nrho)

Value of the radial coordinate of radial grid for which the resonance is evaluated.

xigridfloat or array_like, (nxi)

Value of the pitch of pitch grid for which the resonance is evaluated.

egridfloat or array_like, (ne)

Value of the energy of energy grid for which the resonance is evaluated.

speciesstr

Name of the particle species.

plotbool, optional

If True, the results are not returned but visualized instead.

resonancefloat or array_like, optional

Resonance(s) to be indicated on the plot e.g. m/n=2/1.

omegafloat, optional

Perturbation mode frequency.

The default value assumes stationary perturbation.

axesAxes, optional

The axes where figure is plotted or otherwise new figure is created.

caxAxes, optional

The color bar axes or otherwise taken from the main axes.

Returns:

torfreqarray_like (nrho, nxi) or (nrho, ne) or (nxi, ne)

Evaluated toroidal orbit frequencies if ‘plot’ = False.

polfreqarray_like (nrho, nxi) or (nrho, ne) or (nxi, ne)

Evaluated poloidal orbit frequencies if ‘plot’ = False.

qeffarray_like (nrho, nxi) or (nrho, ne) or (nxi, ne)

Evaluated effective qfactor = torfreq / polfreq if ‘plot’ = False.

input_eval_ripple(rgrid, zgrid, rlarmor, rho0=unyt_quantity(1., 'dimensionless'), theta0=unyt_quantity(0, 'rad'), t=unyt_quantity(0, 's'), nphi=362, plot=True, axes1=None, axes2=None)

Evaluate various ripple quantities.

The variation of toroidal field strength as a function of toroidal angle is called the toroidal field (TF) ripple. The TF ripple can lead to ripple-induced losses provided that i) the particle is trapped in a ripple well in which case it is promptly lost or ii) the ripple causes particle motion to become stochastic which leads to radial diffusion.

This function evaluates the quantities relevant for ripple transport. Note that deltacrit and ripplewell are approximate quantities based on analytical estimates.

Parameters:

rgridarray_like

R points where delta, deltacrit, and ripplewell are evaluated.

zgridarray_like

z points where delta, deltacrit, and ripplewell are evaluated.

rlarmorfloat or tuple (str, int, float)

Larmor radius of the test particle or tuple with (species, charge, energy).

rho0float, optional

Radial coordinate where amplitude is evaluated.

theta0float, optional

Poloidal coordinate where amplitude is evaluated.

tfloat, optional

Time instance for time-dependent fields.

nphiint, optional

Number of toroidal grid points in ripple evaluation.

There is probably never a need to change this number.

plotbool, optional

If True, the evaluated quantities are also plotted.

axes1, optional

Axes for plotting amplitude if plot = True.

axes2, optional

Axes for plotting delta, deltacrit, and ripplewell if plot = True.

Returns:

phigridarray_like, (nphi)

Toroidal grid [-2, 362] where amplitude is given.

This grid is not limited to [0,360] as usual so that one can also use it to spot any discontinuities in field if the input was poorly constructed.

amplitudearray_like, (nphi,)

Variation in toroidal field strength, i.e. Bphi(phi) - Bphi_axisymmetric.

deltaarray_like, (nr,nz)

Ripple magnitude defined as (Bmax-Bmin) / (Bmax+Bmin), where Bmax and Bmin are toroidal extrema of Bphi.

deltacritarray_like, (nr,nz)

Critical ripple magnitude divided by delta.

Particles are subject to stochastic ripple diffusion when deltacrit < 1.

ripplewellarray_like, (nr,nz)

Ripple well parameter.

Particles are bound to be ripple-trapped when ripplewell < 1. However, this does not necessarily mean that the particle is lost as it may escape the well when ripple-trapping causes it to drift outwards. As particles that are ripple-trapped drift vertically, a good indication that a trapped particle will be lost if the ripple well region covers everything vertically below/above that point.

input_eval_safetyfactor(rho, nth=10000)

Evaluate safety factor and associated quantities.

This function most likely works for tokamaks only.

Parameters:

rhoarray_like, (n,)

Radial positions where the safety factor is evaluated.

Note that evaluating it near the axis or exactly at the separatrix may yield mess.

Returns:

qprofarray_like, (n,)

Safety factor.

Iprofarray_like, (n,)

Toroidal current term which, when multiplied with 2pi/mu0, gives the enclosed toroidal current.

gprofarray_like, (n,)

This is just R * Bphi which is constant since Bphi ~ 1/R.

input_initialized()

Get inputs that are currently initialized.

Returns:

outputsdict [str, str]

Name of the input parent groups that are initialized and QID of the initialized input.

input_plotrhocontour(rho=1.0, phi=unyt_quantity(0, 'degree'), t=unyt_quantity(0, 's'), ntheta=180, axes=None, **kwargs)

Plot contours of constant rho.

Calling this without arguments plots the separatrix.

Parameters:

rhofloat or array_like, optional

Value(s) of square root of normalized poloidal flux whose contours are plotted.

phifloat, optional

Toroidal angle at which contours are plotted.

tfloat, optional

Time instance when the contours are plotted.

nthetaint, optional

Poloidal resolution of the contours.

axesAxes, optional

The axes where figure is plotted or otherwise new figure is created.

**kwargs

Arguments passed to matplotlib.pyplot.plot().

input_plotrz(r, z, qnt, phi=unyt_quantity(0, 'degree'), t=unyt_quantity(0, 's'), clim=None, cmap=None, axes=None, cax=None)

Plot input quantity on a (R, z) plane at given coordinates.

To plot quantity on a logarithmic scale (base 10), add “log” in the name of the quantity e.g. “log ne”.

Parameters:

rarray_like (nr,)

R abscissa where data is evaluated and plotted.

zarray_like (nz,)

z abscissa where data is evaluated and plotted.

qntstr

Name of the plotted quantity.

phifloat, optional

Toroidal coordinate where data is evaluated.

tfloat, optional

Time coordinate where data is evaluated.

climlist [float, float], optional

Minimum and maximum color range values.

axesAxes, optional

The axes where figure is plotted or otherwise new figure is created.

caxAxes, optional

The color bar axes or otherwise taken from the main axes.

input_rhovolume(nrho=10, ntheta=360, nphi=10, method='mc', tol=0.1, t=unyt_quantity(0, 's'), return_area=False, return_coords=False)

Evaluate flux surface volumes.

Parameters:

nrhoint, optional

Number of radial grid edges between [0, 1].

nthetaint, optional

Number of poloidal grid edges.

nphiint, optional

Number of toroidal grid edges.

method{“prism”, “mc”}, optional

Method used to evaluate the volumes.

“prism” divides the volume into structured 3D grid consisting of triangular prims where the triangular plane is poloidal and one of the vertices is at magnetic axis while the other two are along a given flux surface. The volume is the estimated as a sum of these prisms.

“mc” divides the volume into toroidal sectors of same size, and on each sector fins the separatrix bounding box. Bounding box is assumed to be fixed along the sector and markers are randomly sampled within it. The volumes are then estimated via the Monte Carlo method.

tolfloat, optional

If relative difference in volume in subsequent iterations falls below this value, the algorithm finishes.

tfloat, optional

Time slice when the volumes are computed.

return_areabool, optional

Return also the area on (R, z) plane.

return_coordsbool, optional

Return also the (R, phi, z) coordinates for grid center points.

Returns:

volumearray_like (nrho-1, ntheta-1, nphi-1)

Volume of each bin.

areaarray_like (nrho-1, ntheta-1, nphi-1)

Area of the poloidal cross section of each bin if return_area=True.

rarray_like (nrho-1, ntheta-1, nphi-1)

R coordinates of bin centers if return_coords=True.

parray_like (nrho-1, ntheta-1, nphi-1)

phi coordinates of bin centers if return_coords=True.

zarray_like (nrho-1, ntheta-1, nphi-1)

z coordinates of bin centers if return_coords=True.