pyGVEC#

python bindings - behind the scenes#

map to buried treasure

The schematic overview of the different layers that make up pyGVEC.#

  • The main part of GVEC is written in modern Fortran (>= Fortran 2003) and compiled as gveclib.

  • The gvec and gvec_post executables are linked with that library.

  • Because the interface between Fortran and Python only works via a C-ABI that does not support any modern features of Fortran, the bindings need several layers of wrappers:

    • A set of Fortran modules that define the API to be exposed to python. Here we can use all Fortran features that are supported by f90wrap.

    • Automatically generated Fortran 90 wrappers generated by f90wrap.

    • Automatically generated C wrappers generated by f2py (we use f90wrap-f2py).

    • Automatically generated Python wrappers generated by f90wrap.

    • A set of python modules that encapsulate the wrappers to provide safety and convenience.

  • The python package for GVEC is separated into several parts:

    • The compiled extension (gveclib + Fortran wrappers + C wrappers) as a shared-library object: gvec._libpygvec

    • The generated python wrapper: gvec.lib

    • A set of core modules, whose key functionality is exposed in the gvec namespace: gvec.run, gvec.Run, gvec.State, etc.

      • The encapsulation of the state for postprocessing: gvec.core.state

      • The encapsulation for running GVEC: gvec.core.run

      • The registration and recursive computation of quantities: gvec.core.compute

    • The built-in quantities: gvec.quantities

    • A general utility module: gvec.util (which may not depend on other modules of gvec!)

    • Additional utility modules: gvec.fourier, gvec.surface, gvec.vtk

    • A set of scripts:

      • The main entry point: gvec.scripts.main - pygvec & pygvec convert-params

      • Running GVEC (with stages, current optimization & diagnostics): gvec.scripts.run - pygvec run

      • Converting to CAS3D: gvec.scripts.cas3d - pygvec to-cas3d

      • Loading a QUASR configuration: gvec.scripts.quasr - pygvec load-quasr

Development Installations#

  • The default pip install creates a temporary virtual environment for building the package. This so called “build isolation” means that every install will recompile GVEC from scratch.

  • By specifying --no-build-isolation this feature can be disabled. pip will now use the current virtual environment and create a CMake build directory pybuild. There you can also inspect the generated wrappers.

  • It is also possible to enable an “editable” install, although this feature (provided by scikit_build_core is still experimental). Then whenever you import gvec a rebuild is triggered.

The recommended installation for local development of the python bindings is therefore:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install --no-build-isolation -ve .

pre-commit#

To keep the python formatting consistent and prevent binary data within the jupyter notebooks to be committed, we use pre-commit:

pip install pre-commit
pre-commit install

Whenever you now commit, a git hook will run ruff and nbclean against all the staged files. It will also try to fix the formatting and clean the notebooks automatically, so you usually just have to git add the files that failed the hook again.