API Reference¶

PegasusTools: Analysis package for the Pegasus PIC code.

class pegasustools.PegasusNBFData(file_path)¶

Bases: object

Holds all the data loaded when loading a NBF file.

It stores all the header data into private variables that are accessible via getters and stores the data arrays in a dictionary named data which is indexed via the variable field names in the NBF file.

Parameters:: file_path (Path)

property big_endian: bool¶

Get the endianness of the NBF file.

Returns:: The endianness of the NBF file. True if the data is big endian, False otherwise.
Return type:: bool

property list_of_variables: list[str]¶

Get the list of variables in the NBF file.

Returns:: The list of variables in the NBF file.
Return type:: list[str]

property mesh_params: dict[str, float32 | int]¶

Get the mesh parameters in the NBF file.

Returns:: The mesh parameters in the NBF file.
Return type:: dict[str, np.float32 | int]

property meshblock_params: dict[str, int]¶

Get the mesh block parameters in the NBF file.

Returns:: The mesh block parameters in the NBF file.
Return type:: dict[str, int]

property num_meshblocks: int¶

Get the number of mesh blocks in the NBF file.

Returns:: The number of mesh blocks in the NBF file.
Return type:: int

property num_variables: int¶

Get the number of variables in the NBF file.

Returns:: The number of variables/fields in the NBF file.
Return type:: int

property time: float64¶

Get the simulation time of the NBF file.

Returns:: The time in the NBF file
Return type:: np.float64

class pegasustools.PegasusSpectralData(file_path, n_prp=200, n_prl=400, max_w_prp=4.0, max_w_prl=4.0)¶

Bases: object

Holds all the data loaded when loading a spectra file.

Stores the time data in a private variable accessible via a getter and stores the spectra data in a numpy array named data

Parameters:

file_path (Path)
n_prp (int)
n_prl (int)
max_w_prp (float)
max_w_prl (float)

property max_w_prl: float | list[float]¶

Get max_w_prl.

Returns:: The value(s) of max_w_prl
Return type:: float | list[float]

property max_w_prp: float | list[float]¶

Get max_w_prp.

Returns:: The value(s) of max_w_prp
Return type:: float | list[float]

property meshblock_locations: DataFrame¶

Get meshblock locations DataFrame.

Returns:: The location data for each meshblock. Keys are: - x1min - x1max - x2min - x2max - x3min - x3max
Return type:: pl.DataFrame

property n_prl: int | list[int]¶

Get n_prl.

Returns:: The value(s) of n_prl
Return type:: int | list[int]

property n_prp: int | list[int]¶

Get n_prp.

Returns:: The value(s) of n_prp
Return type:: int | list[int]

property num_ions: int¶

Get num_ions.

Returns:: The value of num_ion
Return type:: int

reduce_spectra()¶

Reduce the spectra.

Creates two new member variables, spectra_prl and spectra_prp, with the parallel and perpendicular averaged spectrum. Depends on max_w_prp, max_w_prl, n_prp, and n_prl being set correctly.

Return type:: None

property time: float32¶

Get the simulation time of the spectra file.

Returns:: The time in the spectra file
Return type:: np.float32

pegasustools.collate_traces(num_processes, source_dir, destination_dir)¶

Collate the .trace_mpiio_optimized files in a directory into ordered files.

Parameters:

num_processes (int) – The number of processes to use.
source_dir (Path) – The path to the directory with the .trace_mpiio_optimized files
destination_dir (Path) – The path with filename where the parquet files should be created. It will be created if it doesn’t exist.

Return type:

None

pegasustools.collate_tracks_from_ascii(num_processes, source_dir, destination_dir, *, max_parquet_size=2000)¶

Collate the .track.dat files in a directory into ordered files.

Parameters:

num_processes (int) – The number of processes to use.
source_dir (Path) – The path to the directory with the .track.dat files
destination_dir (Path) – The path with filename where the parquet files should be created. It will be created if it doesn’t exist.
max_parquet_size (int, optional) – The maximum parquet file size in MB. This is only approximate and the actual file size might be smaller to help with load balancing. By default 2000MB

Return type:

None

pegasustools.collate_tracks_from_binary(num_processes, source_dir, destination_dir, *, restart_collect=False)¶

Collate the .track_mpiio_optimized files in a directory into ordered files.

Parameters:

num_processes (int) – The number of processes to use.
source_dir (Path) – The path to the directory with the .track_mpiio_optimized files
destination_dir (Path) – The path with filename where the parquet files should be created. It will be created if it doesn’t exist.
restart_collect (bool, optional) – Only run the final collection stage. Intended to be used to restart if the collection step fails due to running out of memory, by default False

Return type:

None

pegasustools.load_hst_file(hst_path)¶

Load the contents of a .hst files as a Polars dataframe.

Automatically corrects for any overlap due to restarts by only accepting the newest/latest data.

Parameters:: hst_path (Path) – The path to the .hst file
Returns:: The Polars dataframe that contains the data from the .hst file. Note that the contents are all in FP32 since the .hst files don’t contain enough precision for FP64.
Return type:: pl.DataFrame
Raises:: RuntimeError – Raised if the .hst files doesn’t have the proper header. Namely it checks that the first line is ‘# Athena++ history datan’ as a quick indicator if this is the proper file type.

pegasustools.setup_pt_logger(logging_level=20, log_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)¶

Create a logger for PegasusTools under the name pt.logger.

Parameters:

logging_level (int, optional) – The logging level to use, by default logging.INFO
log_stream (TextIO, optional) – The stream to send the logs to, by default sys.stdout

Returns:

A Logger object that is fully setup.

Return type:

logging.Logger

API Reference¶

Submodules¶