bluemira.equilibria.analysis

Equilibria and Equilibria optimisation analysis tools

Classes

`EqAnalysis`	Equilibria analysis toolbox for selected Equilibrium.
`MultiEqProfiles`	Profile dataclass for plotting.
`MultiEqAnalysis`	Equilibria analysis toolbox for multiple Equilibrium.

Functions

`select_eq`(...)	Return an Equilibrium or FixedPlasmaEquilibrium object given a particular file name.
`select_multi_eqs`(equilibrium_input[, fixed_or_free, ...])	Put information needed to load eq into a dictionary.
`get_eqs`(equilibria_dict)	Use equilibrium load dictionaries to load equilibrium objects
`get_leg_flux_info`(→ tuple[list[dict[str, ...)	Get the divertor leg length and grazing angle (used in divertor comparison plotting).
`get_target_flux`(...)	Get a selection flux surfaces that cross the divertor target.

Module Contents

bluemira.equilibria.analysis.select_eq(file_path: str, fixed_or_free: bluemira.equilibria.diagnostics.FixedOrFree = FixedOrFree.FREE, dummy_coils: bluemira.equilibria.coils.CoilSet | None = None, from_cocos: int = BLUEMIRA_DEFAULT_COCOS, qpsi_positive: bool = False, control: bluemira.base.constants.CoilType | list[str] | None = None) → bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium | bluemira.equilibria.equilibrium.Equilibrium

Return an Equilibrium or FixedPlasmaEquilibrium object given a particular file name.

Cocos indices and qpsi sign are set to Bluemira Defaults unless specified.

Parameters:

file_path (str) – file path to chosen equilibria
fixed_or_free (bluemira.equilibria.diagnostics.FixedOrFree) – whether or not it is for a fixed plasma boundary
dummy_coils (bluemira.equilibria.coils.CoilSet | None) – coilset if none in equilibria file (a default coilset is used, and a warning message prints if none is provided)
from_cocos (int) – The COCOS index of the EQDSK file. Used when the determined COCOS is ambiguous. Will raise if given and not one of the determined COCOS indices.
qpsi_positive (bool) – Whether or not qpsi is positive, required for identification when qpsi is not present in the file.
control (bluemira.base.constants.CoilType | list[str] | None) – Set which coils are control coils. Can be a coil type, a list of coil names, or None for all coils. N.B. many equilibrium objects already have coilsets with control coils set, and this input may not be necessary.

Returns:

Equilibrium or FixedPlasmaEquilibrium

Return type:

bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium | bluemira.equilibria.equilibrium.Equilibrium

bluemira.equilibria.analysis.select_multi_eqs(equilibrium_input: str | bluemira.equilibria.equilibrium.Equilibrium | collections.abc.Sequence[str | bluemira.equilibria.equilibrium.Equilibrium], fixed_or_free: bluemira.equilibria.diagnostics.FixedOrFree = FixedOrFree.FREE, equilibrium_names: str | collections.abc.Sequence[str] | None = None, dummy_coils: collections.abc.Sequence | None = None, from_cocos: int | collections.abc.Iterable[int] = BLUEMIRA_DEFAULT_COCOS, *, qpsi_positive: bool | collections.abc.Iterable[bool] = False, control_coils: bluemira.base.constants.CoilType | list[str] | None = None)

Put information needed to load eq into a dictionary.

Cocos indices and qpsi sign are set to Bluemira Defaults unless specified.

Parameters:

equilibrium_input (str | bluemira.equilibria.equilibrium.Equilibrium | collections.abc.Sequence[str | bluemira.equilibria.equilibrium.Equilibrium]) – List of chosen equilibria or file paths to chosen equilibria
fixed_or_free (bluemira.equilibria.diagnostics.FixedOrFree) – whether or not it is for a fixed plasma boundary
equilibrium_names (str | collections.abc.Sequence[str] | None) – Names of chosen equilibrium
dummy_coils (collections.abc.Sequence | None) – coilset if none in equilibria file (a default coilset is used, and a warning message prints if none is provided)
from_cocos (int | collections.abc.Iterable[int]) – The COCOS index of the EQDSK file. Used when the determined COCOS is ambiguous. Will raise if given and not one of the determined COCOS indices.
qpsi_positive (bool | collections.abc.Iterable[bool]) – Whether or not qpsi is positive, required for identification when qpsi is not present in the file.
control_coils (bluemira.base.constants.CoilType | list[str] | None) – Set which coils are control coils. Can be a coil type, a list of coil names, or None for all coils. N.B. many equilibrium objects already have coilsets with control coils set, and this input may not be necessary.

Returns:

Dictionary of load info

Return type:

equilibria_dict

Raises:

ValueError – If list of input values is not the same length as the input equilibria

bluemira.equilibria.analysis.get_eqs(equilibria_dict)

Use equilibrium load dictionaries to load equilibrium objects and add the objects to the dictionary.

Parameters:: equilibria_dict – Dictionary of load information for multiple equilibria.
Returns:: Dictionary updated with equilibrium and profile objects.
Return type:: equilibria_dict

bluemira.equilibria.analysis.get_leg_flux_info(eq_list, n_layers=10, dx_off=0.1, plasma_facing_boundary_list=None, legs_to_plot=DivLegsToPlot.ALL) → tuple[list[dict[str, float | numpy.ndarray]], list[dict[str, float | numpy.ndarray]]]

Get the divertor leg length and grazing angle (used in divertor comparison plotting).

Parameters:

eq_list – List of Equilibrium objects to compare
n_layers – Number of flux surfaces to extract for each leg
dx_off – Total span in radial space of the flux surfaces to extract
plasma_facing_boundary_list – List of associated plasma facing boundary coordinates
legs_to_plot – Which legs to plot i.e, upper, lower or all.

Returns:

lengths – Dictionary of connection length values for each named leg.
angles – Dictionary of grazing values for each named leg.

Raises:

BluemiraError – If leg pair is chosen that does not exist in chosen eq.

Return type:

tuple[list[dict[str, float | numpy.ndarray]], list[dict[str, float | numpy.ndarray]]]

bluemira.equilibria.analysis.get_target_flux(eq, target, target_coords, n_layers, vertical=False) → list[bluemira.geometry.coordinates.Coordinates]

Get a selection flux surfaces that cross the divertor target.

eq:: chosen Equilibrium
target:: Location of divertor target, lower_outer, lower_inner, upper_outer or upper_inner
target_coords:: Coordinates of divertor target
n_layers:: Number of flux surfaces to extract for each leg
vertical:: Set to True if using a vertical target. This boolean determines whether to get flux surfaces across the target x-range (horizontal) or z-range (vertical).

Returns:: List of flux surface coordinates.
Return type:: fs_list
Raises:: BluemiraError – If the target is set to vertical or horizontal incorrectly.

class bluemira.equilibria.analysis.EqAnalysis(input_eq: bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium | None = None, reference_eq: bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium | None = None, diag_ops: bluemira.equilibria.diagnostics.EqDiagnosticOptions | None = None)

Equilibria analysis toolbox for selected Equilibrium.

Can compare selected equilibrium to a reference equilibrium. The input and reference equilibria be different types (i.e, fixed or free), and have different grid sizes and grid resolutions.

Parameters:

diag_ops (bluemira.equilibria.diagnostics.EqDiagnosticOptions | None) – Diagnostic plotting options
input_eq (bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium | None) – input equilibrium
reference_eq (bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium | None) – reference equilibrium

input = None

reference = None

diag_ops

set_input(input_eq: bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium)

Sets input equilibrium.

Parameters:: input_eq (bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium)

set_reference(reference_eq: bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium)

Sets reference equilibrium.

Parameters:: reference_eq (bluemira.equilibria.equilibrium.Equilibrium | bluemira.equilibria.equilibrium.FixedPlasmaEquilibrium)

_get_input()

_get_reference()

plot(ax=None)

Plot input equilibria.

Returns:: Matplotlib Axes object
Return type:: ax

plot_field(ax=None)

Plot poloidal and toroidal field for input equilibria.

Returns:: Matplotlib Axes object
Return type:: ax
Raises:: BluemiraError – if wrong number of axes is input

plot_profiles(ax=None)

Plot profiles for input equilibria.

Returns:: Matplotlib Axes object
Return type:: ax

plot_eq_core_analysis(ax=None) → tuple[bluemira.equilibria.flux_surfaces.CoreResults, matplotlib.axes.Axes]

Plot characteristics of the plasma core for input equilibria and return results. Currently only works for free boundary equilibria.

Returns:

core_results – Dataclass for core results.
ax – Matplotlib Axes object

Raises:

BluemiraError – If the equilibrium is fixed boundary.

Return type:

tuple[bluemira.equilibria.flux_surfaces.CoreResults, matplotlib.axes.Axes]

plot_eq_core_mag_axis(ax=None)

Plot a 1-D section through the magnetic axis of the input equilibria. Currently only works for free boundary equilibria.

Returns:: Matplotlib Axes object
Return type:: ax
Raises:: BluemiraError – If the equilibrium is fixed boundary.

physics_info_table() → bluemira.equilibria.physics.EqSummary

Create a table with the physics information from the input equilibria. Not for use with FixedPlasmaEquilibrium.

Returns:: Dataclass of physics information.
Return type:: eq_summary
Raises:: BluemiraError – If the equilibrium is fixed boundary.

control_coil_table(control: list | None = None)

Create a table with the control coil information from the input equilibria. Not for use with FixedPlasmaEquilibrium.

Parameters:: control (list | None) – Set the control coils with a coil type or list of coil names.
Returns:: Table with summary of control coil information.
Return type:: table
Raises:: BluemiraError – If the equilibrium is fixed boundary.

plot_equilibria_with_profiles(ax=None, show=True)

Plot input equilibria alongside profiles.

Parameters:

ax – List of Matplotlib Axes objects set by user
show – Whether or not to display the plot

Returns:

The Matplotlib Axes objects for each subplot.

Return type:

ax1, ax2

Raises:

BluemiraError – if the wrong number of axes is provided

plot_compare_separatrix(title=None, ax=None, show=True)

Plot separatricies of input equilibria and reference equilibria. N.B. Plots LCFS if a fixed boundary is used.

Parameters:

title – Title to be added at top of figure
ax – Matplotlib Axes objects set by user
show – Whether or not to display the plot

Returns:

Matplotlib Axes object

Return type:

ax

plot_compare_psi(diag_ops: bluemira.equilibria.diagnostics.EqDiagnosticOptions | None = None, ax=None)

Plot Psi comparison.

Parameters:

diag_ops (bluemira.equilibria.diagnostics.EqDiagnosticOptions | None) – Diagnostic plotting options
ax – List of Matplotlib Axes objects set by user

Returns:

plotting class

Raises:

BluemiraError – if no reference equilibrium is provided

plot_compare_profiles(reference_profile_sign=None, ax=None, diff=True)

Plot equilibria reference and input profiles. The diff option can be used to plot the difference between the reference and input profiles on the same axis.

Parameters:

reference_profile_sign – To be used with the diff option if the profile convention of the compared equilibria is different.
ax – Matplotlib axes object.
diff – If two equilibria are being compared then we have the option of also plotting the difference between them.

Returns:

Matplotlib Axes object

Return type:

ax

Raises:

BluemiraError – if no reference equilibrium or equilibrium file path is provided
ValueError – if the profile sign array provided is an incorrect length

plot_target_flux(target: str, target_coords: bluemira.geometry.coordinates.Coordinates, use_reference=True, n_layers=10, vertical=False, ax=None, show=True)

Plot the divertor leg flux. Will find flux surfaces at evenly spaced points in x- or z- direction for a set of target coordinates.

Parameters:

target (str) – Location of divertor target, i.e., lower_outer, lower_inner, upper_outer or upper_inner
target_coords (bluemira.geometry.coordinates.Coordinates) – Coordinates of divertor target
use_reference – Plot reference as well as input
n_layers – Number of flux surfaces to extract for each leg
vertical – Set to True if using a vertical target. This boolean determines whether to get flux surfaces across the target x-range (horizontal) or z-range (vertical).
ax – Matplotlib Axes objects set by user
show – Whether or not to display the plot

Returns:

ax – Matplotlib Axes object
target_flux – Coordinates of flux surfaces crossing target for input equilibria
ref_target_flux – Coordinates of flux surfaces crossing target for reference equilibria

class bluemira.equilibria.analysis.MultiEqProfiles

Profile dataclass for plotting.

pprime: list[numpy.typing.NDArray[numpy.float64]] | None = None

ffprime: list[numpy.typing.NDArray[numpy.float64]] | None = None

fRBpol: list[numpy.typing.NDArray[numpy.float64]] | None = None

pressure: list[numpy.typing.NDArray[numpy.float64]] | None = None

shape: list[numpy.typing.NDArray[numpy.float64]] | None = None

add_profile(profile, n_points): Add profile to dataclass.

class bluemira.equilibria.analysis.MultiEqAnalysis(equilibria_dict: dict, n_points: int = 50)

Equilibria analysis toolbox for multiple Equilibrium.

Parameters:

equilibria_dict (dict) – Dictionary of equilibria load information. Can be created using select_multi_eqs function.
n_points (int)

equilibria_dict

set_equilibria(equilibria_dict: dict, n_points: int = 50)

Use dictionary of equilibria information to get values for plotting.

Parameters:

equilibria_dict (dict) – Dictionary of equilibria load information. Can be created using select_multi_eqs function.
n_points (int) – Number of profile points to plot.

make_eq_dataclass_list(method, *args)

Create a list of dataclasses from a function with equilibrium as the first argument.

Parameters:

method – Dataclass creation method.
args – Arguments needed for chosen method.

Returns:

list of dataclass objects

Return type:

results

fill_plotting_profiles(n_points)

Calculate profile values for plotting. This is done when a MultiEqAnalysis class initiated but can be reset with different n_points using this function.

Parameters:: n_points – number of normalised psi points

physics_info_table()

Create a table with the the physics information from all listed Equilibria. Not for use with FixedPlasmaEquilibrium.

Returns:: Table with equilibria physics information.
Return type:: table

plot_core_physics(title='Physics Parameters', n_points: int = 50, ax=None, show=True)

Plot physics parameters for the core plasma of each equilibria (i.e., plot across the normalised 1-D flux coordinate).

title:: Title to be added at top of figure
n_points:: number of normalised psi points
ax:: Matplotlib Axes objects set by user
show:: Whether or not to display the plot

Returns:

core_results – List[dataclass] of equilibria core physics results.
ax – Matplotlib Axes object

Parameters:

n_points (int)

coilset_info_table(value_type=CSData.CURRENT)

Create a table with the the control coil information from all listed Equilibria.

Parameters:: value_type – Choose the type of coilset data to be printed, default is current values.
Returns:: table with equilibria control coil information.
Return type:: table

plot_compare_profiles(ax=None, header=None, n_points=None)

Plot the profiles of all the listed equilibria.

Parameters:

ax – List of Matplotlib Axes objects set by user
header – Text to be added at the top of the figure
n_points – number of normalised psi points

Returns:

The Matplotlib Axes objects for each subplot.

Return type:

ax1, ax2, ax3, ax4, ax5, ax6

Raises:

BluemiraError – if the axes provided are the incorrect shape

plot_compare_flux_surfaces(flux_surface=FluxSurfaceType.LCFS, plot_fixed=True, psi_norm=0.98, title=None, ax=None, show=True)

Plot a flux surface of choice for each equilibrium on the same axes. User can select either the LCFS, separatrix or a flux surface with a given psi_norm.

Always plots a LCFS for a fixed boundary equilibrium, unless plot_fixed is set to false, in which case no flux surfaces are plotted for any fixed boundary equilibria.

Parameters:

flux_surface – Type of flux surface to be plotted
plot_fixed – Weather or not to plot the LCFS for any fixed boundary equilibria.
psi_norm – The normalised psi value to use, if the user selects the psi norm comparison option.
title – Title to be added at top of figure
ax – Matplotlib Axes objects set by user
show – Whether or not to display the plot

Returns:

Matplotlib Axes object

Return type:

ax

plot_divertor_length_angle(n_layers=10, dx_off=0.1, plasma_facing_boundary_list=None, legs_to_plot=DivLegsToPlot.ALL, ax=None, show=True, radian=True)

Plot the divertor leg length and grazing angle for the equilibria divertor legs.

Parameters:

n_layers – Number of flux surfaces to extract for each leg
dx_off – Total span in radial space of the flux surfaces to extract
plasma_facing_boundary_list – List of associated plasma facing boundary coordinates
legs_to_plot – Which legs to plot i.e, upper, lower or all.
ax – Matplotlib Axes objects set by user
show – Whether or not to display the plot
radian – True for plot angles in units of radians False for plot angles in units of degrees

Returns:

Matplotlib Axes object

Return type:

ax