CHiMERA Common

About

See the documentation.

This package provides the submodules

common.logger: a logging module with a Logger class to subclass and a default logger format utility function
common.io: an input/output module with functions to, e.g.,
- read options from YAML input files
- read FEniCSx mesh data
- write option data classes to YAML files
- copy input files
- write system info, write git commit hash (deprecated in favor of capture_environment())
common.timing: timing decorator @timed (FEniCSx based)
common.utils: utility functions, e.g.,
- capture_environment() retrieves environment metadata and writes to YAML files
- a rank0 decorator for serial function execution
- retrieve git commit hash for a repository path

The package also provides a cli program convert_msh2xdmf to convert meshes from GMSH to the FEniCS XDMF format.

The following functionality does not require FEniCSx/DOLFINX to be installed:

common.logger
common.io:
- load_options(): load an options YAML file into a dictionary
- dump_options(): write options dataclasses into a YAML file
- copy_inputfile(): copy a given inputfile to a different path
- write_version_githash(): write the hash of the current git commit to a file (deprecated in favor of capture_environment())
common.utils

Installation

Editable development build

To install an editable version for development:

pip install -e .  --config-settings editable_mode=strict

The editable_mode settings makes the type annotations findable for Mypy in other local projects importing from common.

As a dependency

Set in the pyproject.toml of the package depending on common:

dependencies = [
    "common @ git+https://git.lwp.rug.nl/chimera/common.git@main",
]

Instead of main, a version tag (or git commit hash) can be specified.

Usage

Logger

Example for two classes logging to a log file results/run.log:

from common.logger import default_logger, Logger

class Problem(Logger):
    def __init__(self) -> None:
        super().__init__()  # will set up logger

        self.logger.info("Initializing")

class Solver(Logger):
    def __init__(self) -> None:
        super().__init__()  # will set up logger

        self.problem = Problem()

        self.logger.info("Initializing")

if __name__ == "__main__":
    default_logger("results/run.log", level="INFO")

    solver = Solver()

Input/output

The common.io module provides functions to load/dump options to/from YAML files, DOLFINX specific functions to read meshes, and others. Check the API documentation and see examples in nsx, hyperelastix, etc.

Timing

common.timing implements a simple timing decorator for DOLFINx that measures the time spent on a function call and a function to write the timings to a file. In contrast to dolfinx.common.timed() the result is stored in the module-level variable TIMER_REGISTRY, which enables writing the timings to a file.

Example usage:

from common.timing import timed, write_timings, TIMER_REGISTRY

from time import sleep   # only needed to cause a delay

@timed
def slow_function():
    sleep(5)

@timed("simple name")
def _function_with_cumbersome_name():
    sleep(3)

for i in range(5):
    slow_function()
    _function_with_cumbersome_name()

print(TIMER_REGISTRY)

write_timings("tmp/timings.txt")

The function write_timings() averages the timings obtained on all MPI processes.

Mesh GMSH to XDMF conversion

The package installs a cli mesh conversion tool, see

convert_msh2xdmf -h

Documentation

To build the documentation, install the dependencies with

pip install -e .[doc]

then run

cd doc
make clean && make html

and open the file doc/build/html/index.html in a web browser.

The documentation is hosted here.