dl-py2f 1.4.0

DL_PY2F: A library for Python-Fortran interoperability

DL_PY2F

About

DL_PY2F is an open-source library for the creation of modern interfaces and data structures in Python that can interoperate with existing scientific software written in Fortran and manipulate their data. DL_PY2F is intended for use with Python-based software packages where data are managed using Python/NumPy and need to be accessed for computations performed by Fortran code. A great advantage of DL_PY2F for the application developers is that the attributes of the Python instance are conveniently retrieved by querying their names in a dictionary-like way on the Fortran side. DL_PY2F also provides utility tools to facilitate initialisation and enhancement of the Python instances.

License

DL_PY2F is open source and released under GNU Lesser General Public License v3.0. It is available for download from the repository.

Authors

DL_PY2F was created and implemented by You Lu at STFC Scientific Computing.

Citing DL_PY2F

Applications using DL_PY2F should cite:

You Lu and Thomas W. Keal, Journal of Open Source Software, in preparation

Documentation

A comprehensive Reference Manual is available, covering installation, usage, supported data types, MPI patterns, and the full API.

Project status

The Python-to-Fortran interoperability has been comprehensively tested using GNU, Intel, and Flang/Clang++ compilers. It also works with NVIDIA HPC compilers although currently arrays must be retrieved and altered in the "safe mode" (readonly=.true.) due to a bug in nvfortran.

:warning: Warning: However, the method for Fortran-to-Python interoperability is still undergoing testing and validation. It currently supports the GNU compiler gfortran, the Intel compiler ifx, the LLVM compiler Flang, and the NVIDIA HPC compiler nvfortran.

Getting started

Required libraries and tools

Tools & Libraries	Min. version	Note
g++/gfortran	11
OR icpc/ifort	17
OR icpx/ifx	2024
OR clang++/flang	22
OR nvc++/nvfortran	26.1
cmake	3.16
python3-dev	3.8
python3-numpy	1.21.5

:bulb: The above package names are based on Ubuntu Linux. They may vary on other operating systems.

Using and testing DL_PY2F

DL_PY2F is a mixed ABI/API-level infrastructure and interoperability library rather than a standalone end-user application. It is designed to be embedded into, and driven by, host scientific software rather than invoked directly by users. For this reason, the primary usage documentation for DL_PY2F is provided in the form of a complete, executable example repository. This example demonstrates the full end-to-end workflow, including configuration, compilation, and runtime interaction between Python and Fortran, in a realistic context. The example repository therefore serves as executable documentation for the project:

https://github.com/stfc/dl_py2f-example

The example also works as a test bench for validating DL_PY2F. Please follow the instructions therein to compile and run it.

Apart from the source code on the github repository, DL_PY2F has also been published and deployed in a launchpad.net PPA and can be installed systemwide using apt:

$ sudo add-apt-repository ppa:dl-py2f/ppa

$ sudo apt update

$ sudo apt install dl-py2f

:warning: Since Debian PPA does not allow underscore _, the package name published on launchpad.net is dl-py2f but not dl_py2f.

:bulb: sudo access is required for installing system-wide packages using apt.

Alternatively, DL_PY2F can be installed via PyPI (the pip command):

export FC=gfortran; export CXX=g++

if you use GNU compilers, or using Intel ones

export FC=ifx; export CXX=icpx

or Flang/Clang++

export FC=flang-22; export CXX=clang++-22

or NVIDIA HPC compilers

export FC=nvfortran; export CXX=nvc++

$ python3 -m venv .venv

$ source .venv/bin/activate

$ pip install --upgrade pip

$ pip install dl_py2f

The use of system installed DL_PY2F is also demonstrated in the example package.

For more information about the usage of DL_PY2F please also read the paper: You Lu and Thomas W. Keal, Journal of Open Source Software, in preparation.

Miscellaneous

Support

Please raise an Issue on the project's page if you have a question or find an issue about the code.

Contributing

Contributions are welcome in the form of Issue/PR on github.com.

Acknowledgements

The DL_PY2F library was created during the redevelopment of ChemShell as a Python-based package, which was funded by EPSRC under the grant EP/K038419/1. Ongoing support for the development of DL_PY2F as part of ChemShell is provided under EPSRC grants EP/R001847/1 and EP/W014378/1, and the Computational Science Centre for Research Communities (CoSeC), via the support provided to the Materials Chemistry Consortium. We acknowledge helpful discussions and suggestions for improvement from Paul Sherwood, Joseph Thacker, and Thomas Durrant.