pysi

PySi, short for PySIROCCO, is a python package designed to interface with the SIROCCO code. It can be installed from its own Github repository under the sirocco-rt organisation. Here is the API documentation; see also Tutorials & Plotting for some example usage.

pysi.wind

Contains the user facing Wind class.

class pysi.wind.Wind(root: str, directory: str | None = None, mask_value: int | Callable[[int], bool] = 0, mass_msol: float | None = None, **kwargs: dict)

Bases: WindPlot

Main wind class for PyPython.

Initialize the class.

Parameters:

• root (str) – The root name of the simulation.

• directory (str) – The directory containing the simulation.

• mask_value (int | Callable[[int], bool]) – The value to use for masking the wind cells. If this is a callable, it will be called with the inwind value and should return True if the cell should be masked.

• mass_msol (float) – The mass of the central object in solar masses.

• **kwargs – Additional keyword arguments to pass to the WindBase class

pysi.util

pysi.util.check_array_is_ascending_order(x_in: list | ndarray) → bool

Check if an array is sorted in ascending or descending order.

If the array is not sorted, a ValueError is raised.

Parameters:

x_in (numpy.ndarray, list) – The array to check.

Returns:

Returns True if the array is in ascending order, otherwise will return False if in descending order.

Return type:

bool

pysi.util.find_file_with_pattern(pattern: str, file_path: Path | str = PosixPath('.')) → list[str]

Find files of the given pattern recursively.

This is used to find a number files given a global pattern, i.e. *.spec, *.pf. When *.py is used, it’ll ignore out.pf and py_wind.pf files. To find py_wind.pf files, use py_wind.pf as the pattern.

Parameters:

• pattern (str) – Patterns to search recursively for, i.e. *.pf, *.spec, tde_std.pf

• file_path (str [optional]) – The directory to search from, if not specified in the pattern.

Returns:

The list of files found.

Return type:

list[str]

pysi.util.find_where_target_in_array(x_in: list | ndarray, target: float) → int

Return the index for a given value in an array.

If an array with duplicate values is passed, the first instance of that value will be returned. The array must also be sorted, in either ascending or descending order.

Parameters:

• x_in (numpy.ndarray) – The array of values.

• target (float) – The value, or closest value, to find the index of.

Returns:

The index for the target value in the array x.

Return type:

int

pysi.util.finish_figure(fig: Figure, *, title: str | None = None, hspace: float | None = None, wspace: float | None = None) → Figure

Add finishing touches to a figure.

This function can be used to add a title or adjust the spacing between subplot panels. The subplots will also be given a tight layout.

Parameters:

• fig (Figure) – The figure object to update.

• title (str) – The title of the figure. Underscores are automatically modified so LaTeX doesn’t complain.

• hspace (float) – The amount of vertical space between subplots.

• wspace (float) – The amount of horizontal space between subplots.

Returns:

The updated Figure object.

Return type:

plt.Figure

pysi.util.get_subplot_dims(n_plots: int) → tuple[int, int]

Get the number of rows and columns for the give number of plots.

Returns how many rows and columns should be used to have the correct number of figures available. This doesn’t return anything larger than 3 columns, but the number of rows can be large.

Parameters:

n_plots (int) – The number of subplots which will be plotted

Returns:

dims – The dimensions of the subplots returned as (nrows, ncols)

Return type:

tuple[int, int]

pysi.util.get_subset_in_second_array(x_in: ndarray, y_in: ndarray, x_min: float, x_max: float) → tuple[ndarray, ndarray]

Get a subset of values from two array given xmin and xmax.

The array must be sorted in ascending or descending order. Since we are slicing in Numpy, the arrays return will be a copy of x_in and y_in so the original arrays will not be modified.

Parameters:

• x_in (numpy.ndarray) – The first array to get the subset from, set by xmin and xmax.

• y_in (numpy.ndarray) – The second array to get the subset from.

• x_max (float) – The minimum x value

• x_min (float) – The maximum x value

Returns:

x, y – The subset arrays.

Return type:

numpy.ndarray

pysi.util.plot_pcolor(x: ndarray, y: ndarray, v: ndarray, *, scale: str = 'loglog', vmin: float | None = None, vmax: float | None = None, xlabel: str | None = None, ylabel: str | None = None, fig: Figure | None = None, ax: Axes | None = None, display: bool = False) → tuple[Figure, Axes]

Plot x, y and v on a colour plot.

This function acts as a big wrapper around matplotlib, to plot and create a nice set of figures. By providing a Figure and Axes object, one can add additional data to an already existing plot.

Parameters:

• x (np.ndarray) – The x values for the plot.

• y (np.ndarray) – The y values for the plot.

• v (np.ndarray) – The values to plot.

• scale (str, optional) – The scale for the x and y axes, by default “loglog”. Can be one of “logx”, “logy”, “linlin”, “loglog”.

• vmin (float | None, optional) – The minimum value for the colour bar, by default None.

• vmax (float | None, optional) – The maximum value for the colour bar, by default None.

• xlabel (str | None, optional) – The label for the x axis, by default None.

• ylabel (str | None, optional) – The label for the y axis, by default None.

• fig (plt.Figure | None, optional) – The figure to plot on, by default None. If None, a new figure will be created.

• ax (plt.Axes | None, optional) – The axes to plot on, by default None. If None, a new axes will be created.

• display (bool, optional) – Whether to display the plot, by default False.

Returns:

_description_

Return type:

tuple[plt.Figure, plt.Axes]

pysi.util.plot_scatter(x: ndarray, y: ndarray, *, xmin: float | None = None, xmax: float | None = None, xlabel: str | None = None, ylabel: str | None = None, scale: str = 'logy', fig: Figure | None = None, ax: Axes | None = None, label: str | None = None, alpha: float = 1.0, display: bool = False) → tuple[Figure, Axes]

Plot a set of x and y data.

This function acts as a big wrapper around matplotlib, to plot and create a nice set of figures. By providing a Figure and Axes object, one can add additional data to an already existing plot.

Parameters:

• x (array-like) – The x data to plot.

• y (array-like) – The y data to ploy.

• xmin (float) – The lower boundary of the x axis.

• xmax (float) – The upper boundary of the x axis.

• xlabel (str) – The label for the x axis.

• ylabel (str) – The label for the y axis.

• scale (str) – The scaling for the axes, i.e. logx, loglog, linlin.

• fig (plt.Figure) – A figure object to update.

• ax (plt.Axes) – An axes object to update.

• label (str) – The label to give the data being plotted.

• alpha (float) – The transparency of the line for the data being plotted.

• display (bool) – If True, the figure will be displayed.

Returns:

• fig (plt.Figure) – The figure object.

• ax (plt.Axes) – The axes object.

Return type:

tuple[Figure, Axes]

pysi.util.prepare_fig_and_ax(fig: Figure, ax: Axes, *, default_figsize: tuple[int, int] = (12, 5)) → tuple[Figure, Axes]

Prepare a figure and axes object.

Checks if the provided fig and ax combination are valid. If both are None, then a new fig and ax are created with dimensions (1, 1).

Parameters:

• fig (plt.Figure) – The proposed Figure object.

• ax (plt.Axes) – The proposed Axes object.

• default_figsize (tuple[int, int], optional) – The size of the figure to create, by default (12, 5).

Return type:

tuple[Figure, Axes]

pysi.util.read_file_with_header(file: str) → tuple[list[str], ndarray]

Read a file and extract the header and the contents.

The first line of the file is assumed to be a header which is split into a list of strings. The remaining part of the file is read into a numpy array.

Parameters:

file (str) – The name of the file to read.

Returns:

A tuple containing the header and the contents of the file.

Return type:

tuple[list[str], numpy.ndarray]

pysi.util.remove_extra_axes(fig: Figure, ax: Axes, n_wanted: int, n_panel: int) → tuple[Figure, Axes]

Remove additional axes which are included in a plot.

This should be used if you have 4 x 2 = 8 panels but only want to use 7 of the panels, in this case the 8th panel will be removed.

Parameters:

• fig (plt.Figure) – The Figure object to modify.

• ax (np.ndarray of plt.Axes) – The Axes objects to modify.

• n_wanted (int) – The actual number of plots/panels which are wanted.

• n_panel (int) – The number of panels which are currently in the Figure and Axes objects.

Returns:

• fig (plt.Figure) – The modified Figure.

• ax (plt.Axes) – The modified Axes.

Return type:

tuple[Figure, Axes]

pysi.util.remove_suffix_from_string(string: str, suffix: str) → str

Remove the provided suffix from a string.

The string is only updated if the suffix is at the end of the string.

Parameters:

• string (str) – The string to remove the suffix from.

• suffix (str) – The suffix to remove.

Returns:

The updated string.

Return type:

str

pysi.util.run_py_optical_depth(root: str, file_path: Path | str = PosixPath('.'), *, scatter_surface: float | None = None, verbose: bool = False) → None

Run py_optical_depth with the provided parameters.

Parameters:

• root (str) – The root name of the model.

• file_path ([optional] str) – The directory containing the model.

• scatter_surface ([optional] float) – The scattering optical depth to find the surface of.

• verbose (bool) – Print stdout to the screen.

Return type:

None

pysi.util.run_py_wind(root: str, commands: list[str], file_path: Path | str = PosixPath('.')) → None

Run py_wind with the provided commands.

Parameters:

• root (str) – The root name of the model.

• commands (list[str]) – The commands to pass to py_wind.

• file_path ([optional] str) – The directory containing the model.

Returns:

output – The stdout output from py_wind.

Return type:

list[str]

pysi.util.run_shell_command(command: list[str] | str, file_path: str | Path = PosixPath('.'), *, verbose: bool = False) → CompletedProcess

Run a shell command.

Parameters:

• command (List[str] or str) – The shell command to run. Must either be a single string to call a program, or a list of the program and arguments for the program.

• file_path (str or pathlib.Path [optional]) – The directory to run the command in.

• verbose (bool) – Print stdout to the screen.

Returns:

shell_out – The output of the shell command.

Return type:

subprocess.CompletedProcess

pysi.util.run_windsave2table(root: str, file_path: Path | str = PosixPath('.'), *, ion_density: bool = False, cell_spec: bool = False, version: str | None = None, verbose: bool = False) → None

Run windsave2table in a directory to create the standard data tables.

The function can also create a root.all.complete.txt file which merges all the data tables together into one (a little big) file.

Parameters:

• root (str) – The root name of the Python simulation

• file_path (str) – The directory where windsave2table will run

• ion_density (bool [optional]) – Use windsave2table in the ion density version instead of ion fractions

• cell_spec (bool [optional]) – Use windsave2table to get the cell spectra.

• version (str [optional]) – The version number of windsave2table to use

• verbose (bool [optional]) – Enable verbose output

Return type:

None

pysi.util.set_axes_scales(ax: Axes, scale: str) → Axes

Set the axes scaling for an Axes object.

Parameters:

• ax (plt.Axes) – The matplotlib Axes to update.

• scale (str) – The axes scaling to use.

Returns:

The updated matplotlib Axes.

Return type:

plt.Axes

pysi.util.set_figure_style() → dict

Set default pysi matplotlib parameters.

Returns:

The parameters dictionary.

Return type:

dict

pysi.util.smooth_array(array: list | ndarray, width: int) → ndarray

Smooth a 1D array of data using a boxcar filter.

Parameters:

• array (numpy.array[float]) – The array to be smoothed.

• width (int) – The size of the boxcar filter.

Returns:

smoothed – The smoothed array

Return type:

numpy.ndarray

pysi.util.split_root_and_directory(root: str | Path, directory: str | Path | None) → tuple[str, Path]

Split the root name from its parent directories.

This exists for cases where the root name and parents directory are provided in a single string or Path instance. Typically this is can be done for Wind and Spectrum classes.

If a Wind and Spectrum class are initialised using the old style of providing the root name and directory separately, this function is not required.

Parameters:

• root (str | Path) – The root name of the simulation.

• directory (str | Path | None) – The directory containing the simulation.

Returns:

• root (str) – The root name of the simulation.

• directory (Path) – A Path instance of the directory containing the simulation.

Raises:

ValueError – When the root is not a string or Path instance.

Return type:

tuple[str, Path]

pysi.spec

Contains the user facing Spectrum class.

class pysi.spec.Spectrum(root: str, directory: str | Path | None = None, default_scale: str | None = None, default_spectrum: str | None = None, smooth_width: int = 0)

Bases: SpectrumPlot

Main spectrum class.

Initialize the class.

Parameters:

• root (str) – The root name of the model.

• directory (Union[str, pathlib.Path]) – The directory containing the model.

• default_scale (str) – The default bin scaling to use, either “log” or “lin”.

• default_spectrum (str) – The spectrum to use as the current. Used as the default choice when indexing the class.

• smooth_width (int) – The boxcar filter width to smooth spectra.

pysi.sim

Analyse or modify simulation conditions.

This module contains functions for analysing the quality of a simulation, or for modifying the atomic data or parameter files of a simulation.

pysi.math

Calculate basic quantities.

This sub-module is intended to house various functions for calculating quantities governed my various laws and equations, i.e. gravitational radius. It also includes functions for converting quantities into other quantities.