pyrokinetics.pyro.Pyro

pyrokinetics.pyro.Pyro#

class pyrokinetics.pyro.Pyro(eq_file=None, eq_type=None, eq_kwargs=None, kinetics_file=None, kinetics_type=None, kinetics_kwargs=None, gk_file=None, gk_output_file=None, gk_code=None, gk_type=None, nocos='pyrokinetics', name=None)[source]#

Bases: object

An object able to read, write, run, analyse and plot GK data

Parameters:

eq_file (PathLike, default None) – Filename for outputs from a global equilibrium code, such as GEQDSK or TRANSP. When passed, this will set the ‘eq’ attribute. This can be used to set a local geometry using the function load_local_geometry or load_local.
eq_type (str, default None) – Type of equilibrium file. When set, this will skip file type inference. Possible values are GEQDSK or TRANSP. If set to None, the file type is inferred automatically.
eq_kwargs (Optional[Dict[str, Any]] = None) – Keyword arguments to be used when building an Equilibrium object
kinetics_file (PathLike, default None) – Filename for outputs from a global kinetics code, such as SCENE, JETTO, TRANSP, or pFile. When passed, this will set the ‘kinetics’ attribute. This can be used to set local kinetics using the function load_local_kinetics or load_local.
kinetics_type (str, default None) – Type of kinetics file. When set, this will skip file type inference. Possible values are SCENE, JETTO, TRANSP, or pFile. If set to None, the file type is inferred automatically.
kinetics_kwargs (Optional[Dict[str, Any]] = None) – Keyword arguments to be used when building a Kinetics object.
gk_file (PathLike, default None) – Filename for a gyrokinetics input file (GS2, GENE, CGYRO). When passed, the attributes ‘local_geometry’, ‘local_species’, and ‘numerics’ are set.
gk_output_file (PathLike, default None) – Filename or directory name for gyrokinetics output file(s). For GS2, the user should pass the ‘.out.nc’ NetCDF4 file. For CGYRO, the user should pass the directory containing output files with their standard names. For GENE, the user should pass one of ‘parameters_####’, ‘nrg_####’ or ‘field_####’, where #### is 4 digits identifying the run. If one of these is passed, the others will be found in the same directory. Alternatively, the user should pass the directory containing ‘parameters_0000’, ‘field_0000’ and ‘nrg_0000’.
gk_code (str, default None) – Type of gyrokinetics input file and output file. When set, this will skip file type inference. Possible values are ‘GS2’, ‘CGYRO’, or ‘GENE’. If set to None, the file type is inferred automatically. If gk_code is set, but no gk_file is provided, the corresponding default template file will be read.
gk_type (str, default None) – Deprecated, synonym for gk_code. gk_code takes precedence.
nocos (Union[str, Normalisation])
name (Optional[str])

__init__(eq_file=None, eq_type=None, eq_kwargs=None, kinetics_file=None, kinetics_type=None, kinetics_kwargs=None, gk_file=None, gk_output_file=None, gk_code=None, gk_type=None, nocos='pyrokinetics', name=None)[source]#

Parameters:

eq_file (PathLike | str | None)
eq_type (str | None)
eq_kwargs (Dict[str, Any] | None)
kinetics_file (PathLike | str | None)
kinetics_type (str | None)
kinetics_kwargs (Dict[str, Any] | None)
gk_file (PathLike | str | None)
gk_output_file (PathLike | str | None)
gk_code (str | None)
gk_type (str | None)
nocos (str | ConventionNormalisation)
name (str | None)

Methods

`__init__`([eq_file, eq_type, eq_kwargs, ...])
`add_flags`(flags)	Adds flags to `gk_input`.
`check_gk_code`([raises])	Checks if the current gyrokinetics context is 'valid', meaning it contains a GKInput, Numerics, LocalGeometry, and LocalSpecies.
`convert_gk_code`(gk_code[, template_file])	Convert the current gyrokinetics context to a new one, overwriting any gk_input, gk_file, file_name, run_directory, local_geometry, local_species, and numerics already associated with it.
`convert_physical_units`([norm])	Convert all held quantities from physical units to the generic simulation units of `norm` (defaults to `self.norms`).
`enforce_consistent_beta_prime`()	Force LocalGeometry attribute beta_prime to be consistent with Numerics and LocalSpecies object
`enforce_consistent_pvg`()	Force LocalSpecies attribute domega_drho to be consistent with gamma_exb in Numerics, valid for high-flow states where V_tor = V_ExB.
`get_reference_values`()	Collect the current normalisation reference quantities.
`load_gk_output`([path, local_norm, ...])	Loads gyrokinetics output into Xarray Dataset.
`load_global_eq`(eq_file[, eq_type])	Reads a global equilibrium file, sets the property `eq_file` to that file path, and sets the attribute `eq` to an Equilibrium.
`load_global_kinetics`(kinetics_file[, ...])	Reads a global kinetics file, sets the property `kinetics_file` to that file path, and sets the attribute `kinetics` to a Kinetics.
`load_local`(psi_n[, local_geometry, ...])	Combines calls to `load_local_geometry()` and `load_local_species()`
`load_local_geometry`(psi_n[, local_geometry, ...])	Uses a global Equilibrium to generate `local_geometry`.
`load_local_species`(psi_n[, a_minor])	Uses a global Kinetics to generate `local_species`.
`load_metric_terms`([ntheta, theta])	Uses the local_geometry object to load up the metric tensor terms
`load_numerics`([load_geometry_species_data])	Use to create `numerics` from a set of kwargs.
`load_template_file`(gk_code[, template_file])	Load a template file into the current gyrokinetics context creating a gk_input, gk_file, file_name, run_directory already associated with it.
`read_gk_dict`(gk_dict, gk_code[, no_process])	Reads a dictionary equivalent of a gyrokinetics input file , and set the gyrokinetics context to match the dict
`read_gk_file`(gk_file[, gk_code, no_process, ...])	Reads a gyrokinetics input file, and set the gyrokinetics context to match the new file.
`read_reference_values`(filename)	Load normalisation reference quantities from a JSON file.
`set_reference_values`([tref_electron, ...])	Manually set the reference values used in normalisations
`switch_local_geometry`([local_geometry, show_fit])	Switches LocalGeometry type
`to`(convention)	Converts the LocalGeometry, LocalSpecies, Numerics an GKOutput objects to the specified Convetion
`update_gk_code`([code_normalisation])	Modifies `gk_input` to account for any changes to `local_geometry`, `local_species`, or `numerics`.
`write_gk_file`(file_name[, gk_code, ...])	Creates a new gyrokinetics input file.
`write_reference_values`(filename)	Write the current normalisation reference quantities to a JSON file.

Attributes

`cgyro_input`	Return the raw data from the `GKInput` corresponding to the CGYRO context.
`eq_file`	Path to the global equilibrium file, if it exists.
`eq_type`	The type of global equilibrium (GEQDSK, TRANSP) if it exists, otherwise `None`.
`file_name`	The final path component of `gk_file`, excluding any directories.
`gene_input`	Return the raw data from the `GKInput` corresponding to the GENE context.
`gk_code`	The current gyrokinetics context, expressed as a string.
`gk_file`	The gyrokinetics input file path corresponding to the current gyrokinetics context.
`gk_input`	The `GKInput` object for the current gyrokinetics context.
`gk_output`	The gyrokinetics output for the current gyrokinetics context (gk_code).
`gk_output_file`	The gyrokinetics output file path corresponding to the current gyrokinetics context.
`gs2_input`	Return the raw data from the `GKInput` corresponding to the GS2 context.
`kinetics_file`	Path to the global kinetics file, if it exists.
`kinetics_type`	The type of global kinetics (JETTO, SCENE, TRANSP, pFile) if it exists, otherwise `None`.
`local_geometry`	The `LocalGeometry` instance for the current gyrokinetics context, or if there is no gyrokinetics context (`self.gk_code` is `None`), a `LocalGeometry` instance that isn't assigned to a context.
`local_geometry_type`	Returns the type of `self.local_geometry`, expressed as a string.
`local_species`	The `LocalSpecies` instance for the current gyrokinetics context, or if there is no gyrokinetics context (`self.gk_code` is `None`), a `LocalSpecies` instance that isn't assigned to a context.
`numerics`	The `Numerics` instance belonging to the current gyrokinetics context.
`run_directory`	The directory containing `gk_file`.
`supported_equilibrium_types`	Returns a list of supported `Equilibrium` types, expressed as strings (e.g. GEQDSK, TRANSP).
`supported_gk_inputs`	Returns a list of supported `GKInput` classes, expressed as strings.
`supported_gk_output_readers`	Returns a list of supported `GKOutput` reader classes, expressed as strings.
`supported_kinetics_types`	Returns a list of supported `Kinetics` types, expressed as strings (e.g. JETTO, SCENE, TRANSP).
`supported_local_geometries`	Returns a list of supported `LocalGeometry` classes, expressed as strings.

add_flags(flags)[source]#

Adds flags to gk_input. Sets local_geometry, local_species and numerics to account for any changes. Note that this will overwrite any changes the user has made to these objects that aren’t already reflected in gk_input.

WARNING: Some flag changes are not persistent when writing to file or calling update_gk_code, as calls to GKInput.set will sometimes overwrite flags in unexpected ways.

Parameters:: flags (Dict[str,Any]) – Dict of key-value pairs matching the format of a given gyrokinetics input file. For example, GS2 uses Fortran namelists, so flags should be a dict-of-dicts: one for each group in the namelist.
Return type:: None
Raises:: RuntimeError – If gk_input is None, i.e. the user has not read a gyrokinetics file, or the user has set pyro.gk_code=None.

property cgyro_input: Dict[str, Any] | None#

Return the raw data from the GKInput corresponding to the CGYRO context. If it doesn’t exist, returns None. Has no setter.

Returns:: Dict holding input data for the CGYRO context if it exists, otherwise None.
Return type:: Dict[str,Any] or None

check_gk_code(raises=True)[source]#

Checks if the current gyrokinetics context is ‘valid’, meaning it contains a GKInput, Numerics, LocalGeometry, and LocalSpecies.

Parameters:: raises (bool, default True) – If raises is True, the function raises RuntimeError when any required objects are missing, and returns True otherwise. If raises is False, the function does not raise, and instead returns False when any required objects are missing, and True otherwise.
Returns:: True if the current context is valid, False otherwise
Return type:: bool
Raises:: RuntimeError – If the current context is valid (only when raises is True)

convert_gk_code(gk_code, template_file=None)[source]#

Convert the current gyrokinetics context to a new one, overwriting any gk_input, gk_file, file_name, run_directory, local_geometry, local_species, and numerics already associated with it.

Will create a new context if one is not already present. If provided with a template file, this will be used to create a new GKInput object, which will then be modified by the current local_geometry, local_species, and numerics (if present). If no template file is specified, the default template corresponding to gk_code is used instead.

If you don’t wish to use the current local_geometry, local_species and numerics, it is recommended to use the function read_gk_file instead.

Parameters:

gk_code (str) – The gyrokinetics code to convert to. Must be a value in supported_gk_inputs.
template_file (PathLike, default None) – The template file used to populate the new GKInput created. Note that some inputs in the template file will be overwritten with the contents of the current local_geometry, local_species and numerics. If None, uses the default template file corresponding to gk_code

Return type:

None

Raises:

ValueError – Provided gk_code is not in supported_gk_inputs.
RuntimeError – If check_gk_code() fails.
Exception – A large variety of errors could occur when building a GKInput from a template file, or setting its values using the current local_geometry, local_species, and numerics.

convert_physical_units(norm=None)[source]#: Convert all held quantities from physical units to the generic simulation units of norm (defaults to self.norms).

enforce_consistent_beta_prime()[source]#

Force LocalGeometry attribute beta_prime to be consistent with Numerics and LocalSpecies object

Return type:: None

enforce_consistent_pvg()[source]#

Force LocalSpecies attribute domega_drho to be consistent with gamma_exb in Numerics, valid for high-flow states where V_tor = V_ExB.

In this limit the parallel velocity is related to the ExB flow by: :rtype: None

vpar = (q * R_maj / r) * V_ExB

which implies that the parallel velocity gradient (PVG) term satisfies:

domega_drho = -(q / rho) * gamma_exb

Updates domega_drho for all species to enforce this relationship.

Return type:: None

property eq_file: Path | None#

Path to the global equilibrium file, if it exists. Otherwise returns None. The user should not have to set this manually. There is only one eq_file per Pyro object, shared by all gk_code.

Returns:: Path to the global equilibrium file if it exists, None otherwise.
Return type:: pathlib.Path or None
Raises:: TypeError – If provided value cannot be converted to a pathlib.Path

property eq_type: str | None#

The type of global equilibrium (GEQDSK, TRANSP) if it exists, otherwise None. Has no setter.

Returns:: If a global equilibrium has been loaded, either via load_global_eq() or the constructor, the type of that Equilibrium. If no equilibrium has been loaded, None.
Return type:: str or None

property file_name: str | None#

The final path component of gk_file, excluding any directories. Has no setter.

Returns:: If gk_file is not None, returns the final part of the path (see pathlib.Path.name). Otherwise, None.
Return type:: str or None

property gene_input: Namelist | None#

Return the raw data from the GKInput corresponding to the GENE context. If it doesn’t exist, returns None. Has no setter.

Returns:: Fortran namelist holding input data for the GENE context if it exists, otherwise None.
Return type:: f90nml.Namelist or None

get_reference_values()[source]#

Collect the current normalisation reference quantities.

Returns:: Mapping containing the electron temperature (eV), density (m**-3), magnetic-field reference (tesla), and minor-radius scale (m); the major-radius entry is returned as None when unavailable.
Return type:: dict

property gk_code: str | None#

The current gyrokinetics context, expressed as a string. This is typically the name of the gyrokinetics code (GS2, CGYRO, GENE, etc). If there is no gyrokinetics context (i.e. only global equilibrium or kinetics components exist) this is instead None.

When setting gk_code, the gyrokinetics context. If set to None, the context is voided, and the properties local_geometry, local_species, and numerics will no longer return anything meaningful.

gk_code will be updated automatically when the user calls read_gk_file or convert_gk_code, as these functions create and switch to a new context. If gk_code is set to a new value without first having read a gyrokinetics input file, a new context is created by reading the appropriate default template file, and, if available, copying the current local_geometry, local_species and numerics.

See _switch_gk_context for details on gyrokinetics contexts.

Returns:: The current gyrokinetics context if it exists, otherwise None.
Return type:: str or None
Raises:: ValueError – If set to anything other than one of the strings in supported_gk_inputs or None.

property gk_file: Path | None#

The gyrokinetics input file path corresponding to the current gyrokinetics context. The user should not need to set this manually.

Returns:: If gk_code is not None, the path to the last read/written gyrokinetics file. Otherwise, None.
Return type:: pathlib.Path or None
Raises:: TypeError – If value cannot be converted to pathlib.Path.

property gk_input: GKInput | None#

The GKInput object for the current gyrokinetics context. The user should not need to set this manually.

Returns:: If gk_code is not None, returns the GKInput object for the current gyrokinetics context. Otherwise, returns None.
Return type:: GKInput or None
Raises:: TypeError – If setting to a value which is not an instance of GKInput

property gk_output: Dataset | None#

The gyrokinetics output for the current gyrokinetics context (gk_code).

Returns:: If the user has loaded gyrokinetics output, this will be contained within an Xarray Dataset. If the user hasn’t loaded this, returns`` None``.
Return type:: xarray.Dataset or None

property gk_output_file: Path | None#

The gyrokinetics output file path corresponding to the current gyrokinetics context. The user should not need to set this manually. Due to the varied nature of gyrokinetics outputs, this may point to a single file or a directory.

Returns:: If gk_code is not None, the path to the gyrokinetics output. Otherwise, None.
Return type:: pathlib.Path or None
Raises:: TypeError – If value cannot be converted to pathlib.Path.

property gs2_input: Namelist | None#

Return the raw data from the GKInput corresponding to the GS2 context. If it doesn’t exist, returns None. Has no setter.

Returns:: Fortran namelist object holding input data for the GS2 context if it exists, otherwise None.
Return type:: f90nml.Namelist or None

property kinetics_file: Path | None#

Path to the global kinetics file, if it exists. Otherwise returns None. The user should not have to set this manually. There is only one kinetics_file per Pyro object, shared by all gk_code.

Returns:: Path to the global kinetics file if it exists, None otherwise.
Return type:: pathlib.Path or None
Raises:: TypeError – If provided value cannot be converted to a pathlib.Path

property kinetics_type: str | None#

The type of global kinetics (JETTO, SCENE, TRANSP, pFile) if it exists, otherwise None. Has no setter.

Returns:: If a global kinetics has been loaded, either via load_global_kinetics() or the constructor, the type of that Kinetics. If no kinetics has been loaded, None.
Return type:: str or None

load_gk_output(path=None, local_norm=None, output_convention='pyrokinetics', load_fields=True, load_fluxes=True, load_moments=False, drop_nan=False, netcdf_file=None, **kwargs)[source]#

Loads gyrokinetics output into Xarray Dataset.

Sets the attributes gk_output and gk_output_file for the current context. If provided with a path, will attempt to read output from that path. Otherwise, will infer the path from the value of gk_file.

Parameters:

path (PathLike, default None) –
Path to the gyrokinetics output file/directory. Valid path for each code are:
- GS2: Path to ‘*.out.nc’ NetCDF4 file
- CGYRO: Path to directory containing output files
- GENE: Path to directory containing output files if numbered 0000, otherwise provide one filename from parameters_####, nrg_#### or field_####. Pyrokinetics will search for the other files in the same directory.
If set to None, infers path from gk_file.
local_norm (SimulationNormalisation, default None) – SimulationNormalisation object used to convert between different unit systems
output_convention (ConventionNormalisation, default "pyrokinetics") – Convention to convert output to
load_fields (bool, default True) – Flag to load fields or not
load_fluxes (bool, default True) – Flag to load fluxes or not
load_moments (bool, default False) – Flag to load moments or not
drop_nan (bool, default False) – If NaNs are found in the output then that data is dropped. Off by default
**kwargs – Arguments to pass to the GKOutputReader.

Return type:

None

Raises:

RuntimeError – If no path is provided, and no gk_file exists. Also if there is no current gyrokinetics context (i.e. pyro.gk_code is None).
Exception – Various errors may occur while processing a gyrokinetics output.
NotImplementedError – If there is not GKOutputReader for gk_code.

load_global_eq(eq_file, eq_type=None, **kwargs)[source]#

Reads a global equilibrium file, sets the property eq_file to that file path, and sets the attribute eq to an Equilibrium.

Parameters:

eq_file (PathLike) – Path to a global equilibrium file.
eq_type (str, default None) – String denoting the file type used to create Equilibrium (e.g. GEQDSK, TRANSP). If set to None, this will be inferred automatically
**kwargs – Args to pass to Equilibrium constructor.
self.gk_code.add_flags(self
flags)

Raises:

Exception – Various errors can be raised while reading eq_file and creating an Equilibrium.

Return type:

None

load_global_kinetics(kinetics_file, kinetics_type=None, **kwargs)[source]#

Reads a global kinetics file, sets the property kinetics_file to that file path, and sets the attribute kinetics to a Kinetics.

Parameters:

kinetics_file (PathLike) – Path to a global kinetics file.
kinetics_type (str, default None) – String denoting the file type used to create Kinetics (e.g. SCENE, JETTO, TRANSP, pFile). If set to None, this will be inferred automatically.
**kwargs – Args to pass to Kinetics constructor.

Return type:

None

Raises:

Exception – Various errors can be raised while reading kinetics_file and creating a Kinetics.

load_local(psi_n, local_geometry='Miller', show_fit=False, local_geometry_kwargs=None, local_species_kwargs=None)[source]#

Combines calls to load_local_geometry() and load_local_species()

Parameters:

psi_n (float) – Normalised flux surface on which to calculate local geometry. 0 is the center of the equilibrium, 1 is the Last-Closed-Flux-Surface (LCFS).
local_geometry (str, default "Miller") – The type of LocalGeometry to create, expressed as a string. Must be in supported_local_geometries.
show_fit (bool) – Show fit of LocalGeometry, default is False
local_geometry_kwargs (dict) – Dictionary of kwargs to pass to load_local_geometry
local_species_kwargs (dict) – Dictionary of kwargs to pass to load_local_species

Return type:

None

Raises:

Exception – See exceptions for load_local_geometry() and load_local_species().

load_local_geometry(psi_n, local_geometry='Miller', show_fit=False, **kwargs)[source]#

Uses a global Equilibrium to generate local_geometry. If there is a gyrokinetics context, overwrites the local geometry of that context only. If there is no gyrokinetics context, saves to an ‘unassigned’ local geometry.

Parameters:

psi_n (float) – Normalised flux surface on which to calculate local geometry. 0 is the center of the equilibrium, 1 is the Last-Closed-Flux-Surface (LCFS).
local_geometry (str, default "Miller") – The type of LocalGeometry to create, expressed as a string. Must be in supported_local_geometries.
show_fit (bool, default False) – Flag to show fits to flux surface and poloidal field
**kwargs – Args used to build the LocalGeometry.

Return type:

None

Raises:

RuntimeError – If a global Equilibrium has not been loaded.
ValueError – If psi_n is less than 0 or greater than 1.
Exception – A number of errors may be raised when creating a LocalGeometry.

load_local_species(psi_n, a_minor=None)[source]#

Uses a global Kinetics to generate local_species. If there is a gyrokinetics context, overwrites the local species of that context only. If there is no gyrokinetics context, saves to an ‘unassigned’ local species.

Parameters:

psi_n (float) – Normalised flux surface on which to calculate local geometry. 0 is the center of the equilibrium, 1 is the Last-Closed-Flux-Surface (LCFS).
a_minor (float, default None) – The minor radius of the global Equilibrium. If set to None, this value is obtained from self.eq. It is recommended to only set this if there is no global Equilibrium.

Return type:

None

Raises:

RuntimeError – If a global Kinetics has not been loaded. Raised if a_minor is None, but no global Equilibrium has been loaded.
ValueError – If psi_n is less than 0 or greater than 1.
Exception – A number of errors may be raised when creating a LocalSpecies.

load_metric_terms(ntheta=None, theta=None)[source]#

Uses the local_geometry object to load up the metric tensor terms

Parameters:

ntheta (int default None) – Number of theta points to use when generating the metric tensor terms
theta (ArrayLike default None) – theta points to use when generating the metric tensor terms

Returns:

None – Raises
------
RuntimeError – If a local_geometry has not been loaded.

load_numerics(load_geometry_species_data=False, **kwargs)[source]#

Use to create numerics from a set of kwargs.

Parameters:: load_geometry_species_data (bool) – Boolean to decided whether to load in data from LocalGeometry and LocalSpecies object like beta, gamma_exb
Return type:: None

load_template_file(gk_code, template_file=None)[source]#

Load a template file into the current gyrokinetics context creating a gk_input, gk_file, file_name, run_directory already associated with it.

If you don’t wish to use the current local_geometry, local_species and numerics, it is recommended to use the function read_gk_file instead.

Parameters:

gk_code (str) – The gyrokinetics code to convert to. Must be a value in supported_gk_inputs.
template_file (PathLike, default None) – The template file used to populate the new GKInput created. Note that some inputs in the template file will be overwritten with the contents of the current local_geometry, local_species and numerics. If None, uses the default template file corresponding to gk_code

Return type:

None

Raises:

ValueError – Provided gk_code is not in supported_gk_inputs.
RuntimeError – If check_gk_code() fails.
Exception – A large variety of errors could occur when building a GKInput from a template file, or setting its values using the current local_geometry, local_species, and numerics.

property local_geometry: LocalGeometry | None#

The LocalGeometry instance for the current gyrokinetics context, or if there is no gyrokinetics context (self.gk_code is None), a LocalGeometry instance that isn’t assigned to a context.

The user may set local_geometry using a string matching any of the values in supported_local_geometries, though this will create an empty LocalGeometry instance.

Returns:: If self.gk_code is not None, returns the local_geometry for this gyrokinetics context if it exists. Otherwise, returns an ‘unassigned’ local_geometry if it exists. Failing this, returns None.
Return type:: LocalGeometry or None
Raises:: NotImplementedError – If setting to a value that isn’t an instance of LocalGeometry, or a string matching those in supported_local_geometries, or isn’t None.

property local_geometry_type: str | None#

Returns the type of self.local_geometry, expressed as a string. If self.local_geometry does not exist, returns None. Has no setter.

Returns:: "Miller" if self.local_geometry is of type LocalGeometryMiller. None if self.local_geometry is None, meaning no local geometry is set.
Return type:: str or None
Raises:: TypeError – If self.local_geometry is set to a non-LocalGeometry type and is not None.

property local_species: LocalSpecies | None#

The LocalSpecies instance for the current gyrokinetics context, or if there is no gyrokinetics context (self.gk_code is None), a LocalSpecies instance that isn’t assigned to a context.

Returns:: If self.gk_code is not None, returns the local_species for this gyrokinetics context if it exists. Otherwise, returns an ‘unassigned’ local_species if it exists. Failing this, returns None.
Return type:: LocalSpecies or None
Raises:: TypeError – If setting to a value that isn’t an instance of LocalSpecies or None.

property numerics: Numerics | None#

The Numerics instance belonging to the current gyrokinetics context. If this does not exist, None.

Returns:

The Numerics instance for this gyrokinetics context, or None if this does not exist.

Return type:

Numerics or None

Raises:

TypeError – When setting to an instance of a class other than Numerics or None
RuntimeError – When setting without a gyrokinetics context. Ensure pyro.gk_code is set first.

read_gk_dict(gk_dict, gk_code, no_process=None)[source]#

Reads a dictionary equivalent of a gyrokinetics input file , and set the gyrokinetics context to match the dict

Sets the gk_input, gk_file, file_name, run_directory, local_geometry, local_species, and numerics for this context (Advanced usage: the last three may optionally be skipped using the ‘no_process’ arg).

NOTE: In previous versions, if a global Equilibrium was loaded, then this would read the gk_file but not load local_geometry. Now, it will overwrite a local_geometry created via load_local_geometry, but this can be fixed by calling load_local_geometry again with the appropriate psi_n.

Parameters:

gk_dict (dict) – Dictionary equivalent of gk_input file
gk_code (str, default None) – The type of the gyrokinetics input file, such as ‘GS2’, ‘CGYRO’, or ‘GENE’. If unset, or set to None, the type will be inferred from gk_file. Default is None.
no_process (List[str], default None) – Not recommended for use by users. If this list contains the string ‘local_geometry’, we do not create a LocalGeometry object from this gk_file. Similarly, if the list contains the string ‘local_species’, we do not create a LocalSpecies, and if the list contains the string ‘numerics’, we do not create a Numerics. This should be used if there is an expectation that these objects will not be needed, saving the overhead of creating them. If set to None, all objects will be included.

Return type:

None

Raises:

Exception – A large number of errors could occur when reading a gyrokinetics input file. For example, FileNotFoundError if gk_file is not a real file, or KeyError if the input file is missing some crucial flags. The possible errors and the Exception types associated with them will vary depending on the gyrokinetics code.

read_gk_file(gk_file, gk_code=None, no_process=None, norms=None)[source]#

Reads a gyrokinetics input file, and set the gyrokinetics context to match the new file.

Parameters:

gk_file (PathLike) – Path to a gyrokinetics input file.
gk_code (str, default None) – The type of the gyrokinetics input file, such as ‘GS2’, ‘CGYRO’, or ‘GENE’. If unset, or set to None, the type will be inferred from gk_file. Default is None.
no_process (List[str], default None) – Not recommended for use by users. If this list contains the string ‘local_geometry’, we do not create a LocalGeometry object from this gk_file. Similarly, if the list contains the string ‘local_species’, we do not create a LocalSpecies, and if the list contains the string ‘numerics’, we do not create a Numerics. This should be used if there is an expectation that these objects will not be needed, saving the overhead of creating them. If set to None, all objects will be included.
norms (SimulationNormalisation | None)

Return type:

None

Raises:

read_reference_values(filename)[source]#

Load normalisation reference quantities from a JSON file.

Parameters:: filename (PathLike) – Path to the JSON file written by write_reference_values.
Return type:: None

property run_directory: Path | None#

The directory containing gk_file. Has no setter.

Returns:: If gk_file is not None, returns directory that contains gk_file. Otherwise, None.
Return type:: pathlib.Path or None

set_reference_values(tref_electron=None, nref_electron=None, bref_B0=None, lref_minor_radius=None, lref_major_radius=None, convert_pyro=True)[source]#

Manually set the reference values used in normalisations

Parameters:

tref_electron ([eV] pint.Quantity) – Electron temperature
nref_electron ([meter**-3] pint.Quantity) – Electron density
bref_b0 ([tesla] pint.Quantity) – Toroidal magnetic field at centre of flux surface
lref_minor_radius ([meter] pint.Quantity) – Minor radius of last closed flux surface
lref_major_radius ([meter] pint.Quantity) – Major radius of local flux surface
convert_pyro (bool default True) – Flag to convert the whole pyro object to specified Convention

Return type:

None

property supported_equilibrium_types: List[str]#

Returns a list of supported Equilibrium types, expressed as strings (e.g. GEQDSK, TRANSP). The user can add new Equilibrium reader classes by ‘registering’ them with Equilibrium.reader

Returns:: Supported Equilibrium file types expressed as strings.
Return type:: List[str]

property supported_gk_inputs: List[str]#

Returns a list of supported GKInput classes, expressed as strings. The user can add new GKInput classes by ‘registering’ them with GKInput.reader

Returns:: List of supported GKInput classes, expressed as strings.
Return type:: List[str]

property supported_gk_output_readers: List[str]#

Returns a list of supported GKOutput reader classes, expressed as strings. The user can add new GKOutput reader class by ‘registering’ them with GKOutput.reader

Returns:: List of supported GKOutput reader classes, expressed as strings.
Return type:: List[str]

property supported_kinetics_types: List[str]#

Returns a list of supported Kinetics types, expressed as strings (e.g. JETTO, SCENE, TRANSP). The user can add new Kinetics reader classes by ‘registering’ them with Kinetics.reader

Returns:: List of supported Kinetics file types, expressed as strings.
Return type:: List[str]

property supported_local_geometries: List[str]#

Returns a list of supported LocalGeometry classes, expressed as strings. The user can add new LocalGeometry classes by ‘registering’ them with local_geometry.local_geometry_factory.

Returns:: List of supported LocalGeometry classes, expressed as strings.
Return type:: List[str]

switch_local_geometry(local_geometry=None, show_fit=False, **kwargs)[source]#: Switches LocalGeometry type

to(convention)[source]#

Converts the LocalGeometry, LocalSpecies, Numerics an GKOutput objects to the specified Convetion

Parameters:: convention (ConventionNormalisation) – ConventionNormalisation to convert all objects to
Return type:: None

update_gk_code(code_normalisation=None)[source]#

Modifies gk_input to account for any changes to local_geometry, local_species, or numerics. Only modifies the current context, as specified by gk_code.

code_normalisation: str, default None: When writing a file this selects which normalisation convention to use when populating the input file. If unset or set to None, the default for each code is used

Return type:: None
Raises:: RuntimeError – If check_gk_code() fails
Parameters:: code_normalisation (str | None)

write_gk_file(file_name, gk_code=None, template_file=None, code_normalisation=None, enforce_quasineutrality=True)[source]#

Creates a new gyrokinetics input file. If gk_code is None, or the same as the current context, this will call update_gk_code within the current context before writing. If gk_code instead corresponds to a different existing context, update_gk_code is called within that context before writing a file.

If gk_code corresponds to a context that does not already exist, a new gyrokinetics context is created using the template file provided. If no template file is provided, the default template file for that gk_code is used. The provided template file is ignored if gk_code corresponds to an existing context, and a warning will be raised.

This function will not change the context to gk_code, unless an exception is raised part way through the function call, in which case the scenario could be either the current context of that of the provided gk_code. The Pyro object may be in an unstable state if this occurs.

Parameters:

file_name (PathLike) – Path to the new file. If file_name exists, the file will be overwritten.
gk_code (str, default None) – The type of the gyrokinetics input file to write, such as ‘GS2’, ‘CGYRO’, or ‘GENE’. If unset, or set to None, self.gk_code is used.
template_file (PathLike, default None) – When writing to a new gk_code, this file will be used to populate the new GKInput created, which will in turn be updated using the current values of local_geometry, local_species and numerics (if available). If gk_code corresponds to a context that already exists, this argument is ignored and a warning is raised.
code_normalisation (str, default None) – When writing a file this selects which normalisation convention to use when populating the input file. If unset or set to None, the default for each code is used
enforce_quasineutrality (bool, default True) – When writing a GK file check for quasineutrality before writing a GK file, if True then an error will be raised, otherwise a warning will be raised

Return type:

None

Raises:

ValueError – If gk_code is not None, and not in supported_gk_inputs.
Exception – Various errors may be raised while processing template_file, calling update_gk_code(), or when writing to disk.

write_reference_values(filename)[source]#

Write the current normalisation reference quantities to a JSON file.

Parameters:: filename (PathLike) – Path to the file where the reference values will be written.
Return type:: None

pyrokinetics.pyro.Pyro

Contents

pyrokinetics.pyro.Pyro#