pencil.util

General utility functions.

This is the bottom layer of the pencil package hierarchy, so modules defined here are not allowed to import any other pencil packages.

Attributes

`MARKER_FILES`
`pc_print`

Classes

`PathWrapper`	See documentation of pathlib.Path.
`SinglePrinter`	Instances of this class will print their output only on the MPI root process.
`DotDict`	A dict subclass that also supports attribute-style access.

Functions

`is_sim_dir`([path])	Decide if a path is pointing at a pencil code simulation directory.
`ffloat`(x)	Numbers are read from fortran code, which has a specific lenght, in this case 8 char
`copy_docstring`(original)	Decorator, to be used for wrapper functions, that makes the docstring of a

Package Contents

pencil.util.MARKER_FILES = ['run.in', 'start.in', 'src/cparam.local', 'src/Makefile.local']

pencil.util.is_sim_dir(path='.')

Decide if a path is pointing at a pencil code simulation directory.

The heuristics used is to check for the existence of start.in, run.in, src/ cparam.local and src/Makefile.local .

pencil.util.ffloat(x)

Numbers are read from fortran code, which has a specific lenght, in this case 8 char If we have scientific notation, it cuts the e and the number doesn’t make sense. Example: Instead of 3.76e-291 it will write 3.76-291

This function checks and converts all numbers to scientific notation in this case

KG (2024-Apr-20): it is unclear why this function is needed at all. float() seems to correctly handle both “3.76e-291” and “3.76E-291”, which are what the Fortran code outputs. This function does the conversion ‘3.76-291’ -> 3.76e-291, but are there any scenarios where the Fortran code produces incorrectly formatted numbers like that?

class pencil.util.PathWrapper

Bases: pathlib.WindowsPath if os.name == 'nt' else pathlib.PosixPath

See documentation of pathlib.Path.

This wrapper tries to avoid immediately breaking user code which assumes paths are always strings

KG (2024-Oct-10): added KG (2024-Nov-09): fixed usage with Python<3.12 (see https://stackoverflow.com/a/78471242 )

Construct a PurePath from one or several strings and or existing PurePath objects. The strings and path objects are combined so as to yield a canonicalized path, which is incorporated into the new PurePath object.

class pencil.util.SinglePrinter

Instances of this class will print their output only on the MPI root process.

KG (2025-Feb-07): added KG (2025-Dec-03): optimized to import mpi4py only when really needed

property print: This logic really belongs in __init__, but we do things this way because importing mpi4py.MPI is very slow. If mpi4py.MPI were imported in __init__, that alone would account for half the initialization time of the Pencil module

pencil.util.pc_print

pencil.util.copy_docstring(original)

Decorator, to be used for wrapper functions, that makes the docstring of a particular function the same as another function.

Rationale: if you consider pc.read.aver and pc.read.averages.Averages.read, both the docstrings are currently independently defined, but the former is simply a wrapper for the other. When new functionality is added to the latter, the docstring for the former is almost never updated, leading to the users being shown outdated help text.

Copied from https://softwareengineering.stackexchange.com/a/386758

NOTE: since sphinx-autoapi (used to generated the readthedocs pages) does not know about this decorator, it is best to manually add a minimal docstring of the form “”” Wrapper for Averages.read() “”” to the wrapper function; this will allow Sphinx to create a link to the original function.

class pencil.util.DotDict

Bases: dict

A dict subclass that also supports attribute-style access.

This allows sim.param to be used both as a dict (sim.param[‘key’]) and with attribute access (sim.param.key), so that it is compatible with the Param objects returned by pc.read.param() and accepted by all reading routines.

Initialize self. See help(type(self)) for accurate signature.