MISHKA plugin

MISHKA is an ideal MHD stability code. Given an equilibrium and a toroidal mode number \(N_{tor}\), MISHKA solves the growth rate of that mode number.

This module provides MishkaParser, which handles reading and writing the MISHKA namelist (fort.10) and parsing key output files produced by MISHKA (fort.20, fort.22). It also supports reading HELENA output files (fort.12, fort.17) when needed.

The parser is used by MishkaRunner for preparing runs and summarizing results.

MishkaParser

MishkaParser(default_namelist)

Bases: Parser

Parser for MISHKA input/output and HELENA equilibrium files.

The parser handles:

Writing the MISHKA namelist file (fort.10) from a supplied template.
Updating eigenvalue guesses in an existing fort.10.
Reading MISHKA output files (fort.20, fort.22).
Reading HELENA output files (fort.12, fort.17) when needed.

Parameters:

Name	Type	Description	Default
`default_namelist`	`str`	Path to the default MISHKA namelist template used to generate fort.10.	required

clean_output_files

clean_output_files(run_dir)

Remove intermediate MISHKA output files from the run directory.

This helps keep the run directory tidy by removing files that are not needed for later analysis.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Path to the run directory.	required

read_input_density

read_input_density(run_dir)

Read HELENA density output file (fort.17).

This file is sometimes used as auxiliary input to MISHKA, containing electron density profiles.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Directory containing `fort.17`.	required

Returns:

Type	Description
	tuple[int, list[float], list[float]] \| None: If the file exists,
	returns (NRMAP, sgrid, ne) where: `NRMAP`: number of radial grid points. `sgrid`: flux coordinate grid (sqrt(psi/psi_boundary)). `ne`: electron density values. Returns `None` if `fort.17` is not present.

read_input_fort12

read_input_fort12(run_dir)

Read HELENA equilibrium output file fort.12.

This method parses the HELENA output into a collection of arrays and scalars needed for configuring a MISHKA run.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Directory containing `fort.12`.	required

Returns:

Name	Type	Description
`tuple`		A tuple containing parsed HELENA quantities in the following order: (JS0, CS, QS, DQS_1, DQS, CURJ, DJ0, NCHI, CHI, GEM11, GEM12, CPSURF, RADIUS, GEM33, RAXIS, P0, DP0, RBPHI, DRBPHI0, VX, VY, EPS, XOUT, YOUT)

read_multiline_list

read_multiline_list(
    lines, startline, n_listitems, n_columns=4, dtype=float
)

Read a list of values split across multiple lines.

Many MISHKA input/output files store long arrays across multiple lines. This helper reads a specified number of values spanning several lines and returns the flat list along with the line index where reading ended.

Parameters:

Name	Type	Description	Default
`lines`	`list[str]`	List of file lines (typically from `file.readlines()`).	required
`startline`	`int`	Index of the first line to read (0-based).	required
`n_listitems`	`int`	Total number of scalar items to read.	required
`n_columns`	`int`	Number of values per line (default: 4).	`4`
`dtype`	`type`	Type to which each value should be converted (default: float).	`float`

Returns:

Type	Description
	tuple[list, int]: A tuple of (values, endline) where `values` is the flattened list of parsed items and `endline` is the next line index after the last line read.

read_output_fort20

read_output_fort20(run_dir)

Parse MISHKA output from fort.20.

This method searches fort.20 for a line beginning with INSTABILITY and extracts the growth rate and iteration count from that line.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	The directory containing `fort.20`.	required

Returns:

Type	Description
	tuple[bool, tuple[float, float]\|None, int]:
	A tuple containing success flag, growth rate tuple, and iteration
	count. `success`: `True` if an instability line was found. `growthrate`: Tuple of (real, imag) growth rate values, or `(None, None)` if not found. `iteration`: Iteration count extracted from the instability line (or -1 if not found).

read_output_fort22

read_output_fort22(run_dir)

Parse the MISHKA fort.22 output file.

The file contains a list of eigenvalues and associated metadata. This method reads the file and returns the key values needed for post- processing.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Directory containing `fort.22`.	required

Returns:

Name	Type	Description
`tuple`		A tuple containing (gamma, ng, manz, ngl, nbg, rfour, sgrid, ev) where: `gamma`: complex growth rate eigenvalue. `ng`: number of grid points. `manz`: number of poloidal harmonics. `ngl`: fixed value (typically 2). `nbg`: number of eigenvalues per harmonic (`2 * ngl * manz`). `rfour`: parameter describing the lowest poloidal mode number. `sgrid`: flux coordinate grid (`sqrt(psi/psi_boundary)`). `ev`: array of complex eigenvalues.

update_eigenvalue_guess

update_eigenvalue_guess(run_dir, new_guesses)

Update eigenvalue guess entries (nshift and vshift) in fort.10.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Path to the run directory containing `fort.10`.	required
`new_guesses`	`list[tuple[float, float]]`	List of (real, imag) tuples representing new vshift guesses.	required

Raises:

Type	Description
`FileNotFoundError`	If `run_dir` or `fort.10` does not exist.

write_input_file

write_input_file(params, run_dir)

Write the MISHKA namelist file (fort.10) for a run.

The method reads the template namelist from self.default_namelist and updates the toroidal mode number (ntor) based on params.

Parameters:

Name	Type	Description	Default
`params`	`dict`	Dictionary of parameters for the MISHKA run. Must contain `ntor`.	required
`run_dir`	`str`	Directory where `fort.10` should be written.	required

Raises:

Type	Description
`FileNotFoundError`	If `run_dir` does not exist.

write_summary

write_summary(run_dir, mpol, params)

Generates a summary of a MISHKA run.

The summary includes run metadata, success status, growth rate, and iteration count. When a successful result is present, it also saves an ntor_growthrate.npy file for quick analysis.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Path to the run directory.	required
`mpol`	`int`	Poloidal harmonic used for the run.	required
`params`	`dict`	Dictionary containing input parameters (must include `ntor`).	required

Returns:

Name	Type	Description
`dict`		Summary dictionary containing run metadata and results.

This module provides the MishkaRunner class which wraps invocation of pre-compiled MISHKA executables (compiled for some specific poloidal harmonics \(M_{pol}\)) and manages input/output file handling.

The module also provides get_mpol() for selecting the correct poloidal harmonic (m) from the toroidal mode (ntor) following the Europed convention. See runner desctiption below for details.

Configuration

The toridal mode number ntor must be defined as a sampling parameter. A path to the directory containing the HELENA output files can also optionally be defined.

Below is an example of a configuration setup. This example will run MISHKA for mode numbers 5, 7 and 10 for three equilibria defined by parameter helena_dir.

``yaml runner: type: MishkaRunner executable_path: "/path/to/mishka/executable" other_params: namelist_path: "/path/to/fort.10"

sampler

type: ArraySampler bounds: [ [5,7,10], ['path/to/helena/run1', 'path/to/helena/run2', 'path/to/helena/run3'], ] num_samples: [7, 3] parameters: ['ntor', 'helena_dir']

``

MishkaRunner

MishkaRunner(
    executable_path, other_params, *args, **kwargs
)

Bases: Runner

MISHKA in an ideal MHD stability code that analyzes plasma equilibria (fort.12) to compute growth rates of instabilities. This runner manages MISHKA execution by:

selecting the correct pre-compiled binary based on the requested toroidal mode number (ntor) and the corresponding poloidal harmonic m (see get_mpol)
ensuring required inputs exist (namelist and equilibrium file fort.12)
copying/symlinking equilibrium files into the run directory
writing/reading MISHKA input and summary files via MishkaParser.

Notes

The runner expects that MISHKA binaries are available with names like {executable_path}_{mpol} where mpol is one of 21, 31, 41, 51, 71.

Parameters:

Name	Type	Description	Default
`executable_path`	`str`	Base path to the MISHKA executable (without the `_{mpol}` suffix).	required
`other_params`	`dict`	A config dict containing at minimum `namelist_path` and optionally `input_fort12` and `input_density`.	required

Attributes:

Name	Type	Description
`parser`	`MishkaParser`	Parser used to generate input and parse output files.
`executable_path`	`str`	The configured base MISHKA executable path (without the `_{mpol}` suffix).
`default_namelist`	`str`	Path to the default namelist file used by MISHKA.
`input_fort12`	`str`	Path to the equilibrium fort.12 file.
`input_density`	`str`	Path to the optional density file.

Methods:

Name	Description
`single_code_run`	Run a single MISHKA calculation and return the result summary.
`run_mishka`	Invoke the appropriate MISHKA binary and capture its output.
`get_equilibrium_files`	Copy/symlink equilibrium files into the run directory.
`pre_run_check`	Validate required files and configuration before running.

get_equilibrium_files

get_equilibrium_files(run_dir)

Copy or symlink equilibrium input files into the run directory.

The runner requires a valid HELENA equilibrium file (fort.12) to be present in run_dir so MISHKA can read it. If input_density is configured, it can also be copied, but this is currently unused by the present MISHKA binaries.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Directory where equilibrium files should be made available for MISHKA.	required

Raises:

Type	Description
`FileNotFoundError`	If the configured `input_fort12` file does not exist.

Notes

This method creates a symlink to the configured fort.12 file (using the basename) so that the run directory can be cleaned up without affecting the original source file.

pre_run_check

pre_run_check(run_dir, params)

Perform pre-run validation and locate required input files.

This method ensures that:

the expected MISHKA binaries exist for all supported ntor values
the configured namelist exists
the equilibrium file (fort.12) can be located via either:
the configured input_fort12 path,
params['helena_dir']/fort.12, or
run_dir's parent directory.

Parameters:

Name	Type	Description	Default
`run_dir`	`str`	Directory where the MISHKA run will occur.	required
`params`	`dict`	Parameters passed to the run, typically including `ntor` and optionally `helena_dir`.	required

Returns:

Name	Type	Description
`str`		An empty string if all checks pass; otherwise an error message.

run_mishka

run_mishka(mpol, run_dir)

Invoke the MISHKA executable and capture its output.

The method runs the pre-compiled binary {executable_path}_{mpol} in the provided run_dir and streams stdout/stderr to mishka_output.log. After completion, the final few log lines are scanned for ERROR to detect fatal Fortran failures.

Parameters:

Name	Type	Description	Default
`mpol`	`int`	The poloidal harmonic number (used to select the executable suffix).	required
`run_dir`	`str`	Directory where the MISHKA run is executed and logs are stored.	required

Returns:

Name	Type	Description
`bool`		`True` if no `ERROR` lines were detected in the final log lines, `False` otherwise.

single_code_run

single_code_run(params, run_dir)

Run MISHKA for a single set of input parameters.

This method performs the full MISHKA workflow:

Validate required files and configuration via pre_run_check.
Ensure equilibrium files exist in the run directory via get_equilibrium_files.
Generate the input namelist via MishkaParser.
Execute the appropriate MISHKA binary via run_mishka.
Parse and summarize results via MishkaParser.write_summary.

Parameters:

Name	Type	Description	Default
`params`	`dict`	Dictionary of parameters for the MISHKA run. Must include `ntor`.	required
`run_dir`	`str`	Directory in which to run MISHKA (inputs are written here and outputs are stored here).	required

Returns:

Name	Type	Description
`dict`		A summary dictionary containing these keys (at minimum): - `success` (bool) - `start_time` (str) - `end_time` (str) - `mishka_dir` (str) - `mpol` (int) - `growthrate` (float or None) - `iterations` (int or None) - `mishka_error` (str)

get_mpol

get_mpol(n)

Select the poloidal harmonic (mpol) based on the toroidal mode (ntor).

This mapping follows the Europed (S. Saarelma) convention used by the MISHKA pre-compiled binaries. The returned mpol value is used as a suffix to select the executable variant ({executable_path}_{mpol}).

Parameters:

Name	Type	Description	Default
`n`	`int`	The toroidal mode number (`ntor`).	required

Returns:

Name	Type	Description
`int`		The poloidal harmonic (`mpol`) to use for selecting the right binary.