fckitlib: Fortran-Python Bridging Library

0.14.2.19 · active · verified Thu Apr 16

fckitlib is a Python library designed to build Python modules on top of existing Fortran codebases. It provides utilities for seamless argument passing, handling Fortran derived types and allocatable arrays, and logging within Fortran components. It is primarily used in scientific computing, particularly with models developed by ECMWF. The current version is 0.14.2.19, with active development and frequent releases (multiple per year), typically supporting Python 3.7+.

Common errors

```
ModuleNotFoundError: No module named 'fckit.fclib'
```
cause The `fckit.fclib` module, which provides Python bindings to an example Fortran library, was not successfully built and installed alongside `fckitlib` itself, or it is not discoverable in the Python path. This module requires Fortran compilation.

fix Verify that `fckitlib` was installed from source with Fortran support enabled. Check installation logs for compilation errors. Ensure that any relevant shared libraries (`.so`, `.dylib`, `.dll`) created during the build process are in your system's library path (e.g., `LD_LIBRARY_PATH` or `PATH`). If using pre-built wheels, ensure they include Fortran bindings for your system.
```
TypeError: Argument 'arg_name' has incorrect type (expected fckit.types.FortranType, got PythonType)
```
cause You are attempting to pass a standard Python object (e.g., `str`, `list`, `int`) directly to a Fortran function exposed via `fckitlib` that expects a specific Fortran-compatible data type or an `fckitlib` wrapper type.

fix Convert the Python object to the appropriate `fckitlib`-specific Fortran type using utilities from `fckit.types` (e.g., `fckit.types.array_ptr` for arrays, `fckit.types.string_ptr` for strings) before passing it to the Fortran function.
```
ImportError: DLL load failed while importing _some_fortran_module: The specified module could not be found. (Windows) or ImportError: dlopen(..., 0x0006): symbol not found in flat namespace '_some_fortran_symbol' (Linux/macOS)
```
cause This error typically occurs when `fckitlib` or a module it generates (to interface with Fortran) tries to load a shared library (`.dll`, `.so`, `.dylib`) that is missing, has unmet dependencies, or contains an undefined symbol required by the Fortran code.

fix Ensure that all required Fortran libraries that your `fckitlib`-wrapped code depends on are compiled, correctly linked, and discoverable in your system's library search path (e.g., `PATH` on Windows, `LD_LIBRARY_PATH` on Linux, `DYLD_LIBRARY_PATH` on macOS). Use tools like `ldd` (Linux) or `Dependency Walker` (Windows) to check shared library dependencies.

Warnings

breaking The signature of `fckit_c_call_fortran` changed, which is a breaking change for users implementing custom Fortran wrappers or C interfaces.
Fix: Review the `CHANGELOG.md` and `fckitlib` C API documentation. Update any custom C interfaces or Fortran wrappers to match the new `fckit_c_call_fortran` signature.
breaking The `fckit.cxx` module was renamed to `fckit.cpp` to better reflect its purpose and avoid confusion.
Fix: Update all import statements and references from `fckit.cxx` to `fckit.cpp` in your Python code.
breaking The `string_ptr` type was moved from `fckit.fclib.types` to `fckit.types` for broader applicability.
Fix: Change import paths for `string_ptr` from `from fckit.fclib.types import string_ptr` to `from fckit.types import string_ptr`.
gotcha Installation and runtime of `fckitlib` often require a Fortran compiler (e.g., gfortran) and specific environment setup (e.g., `LD_LIBRARY_PATH` on Linux/macOS, `PATH` on Windows) for linked Fortran libraries to be found. Compilation issues are common if the environment is not correctly configured.
Fix: Ensure a compatible Fortran compiler is installed and accessible. Consult the `fckitlib` documentation and your operating system's guidelines for setting up shared library paths, especially when building from source or linking to external Fortran libraries.

Install

pip install fckitlib Install fckitlib

Imports

Logger
```
from fckit.log import Logger
```
fclib
```
from fckit import fclib
```
Requires the fclib example module to be built and discoverable, typically via fckitlib installation with Fortran support.
array_ptr
```
from fckit.types import array_ptr
```
string_ptr
wrong:
```
from fckit.fclib.types import string_ptr
```
correct:
```
from fckit.types import string_ptr
```
The 'string_ptr' type was moved from 'fckit.fclib.types' to the more general 'fckit.types' in version 0.12.0.

Quickstart

This quickstart demonstrates initializing `fckitlib`'s pure Python-side logger. It also includes a conceptual example of loading the `fclib` Fortran example module, which requires `fckitlib` to be built with Fortran support and correctly installed, allowing Python to interface with compiled Fortran functions and types.

from fckit.log import Logger

# Initialize a pure Python-side logger provided by fckitlib
# In a full Fortran-interfaced application, this logger could
# be configured to be accessible from the Fortran side as well.
logger = Logger("my_fckit_app")
logger.info("fckitlib Logger initialized successfully!")
logger.warning("This is a Python-side log message.")

# Example of attempting to load the fckitlib Fortran example module
# This part is conceptual; actual Fortran interaction requires fckitlib
# to be built with Fortran support and correctly linked.
try:
    from fckit import fclib
    print(f"\nfckitlib fclib module loaded. Fortran version: {fclib.version_str()}")
    # Further interaction with Fortran functions/types from fclib would go here
except ImportError:
    print("\nWarning: fckit.fclib module not found. It might not be built or installed correctly with Fortran support.")
except Exception as e:
    print(f"\nError loading fckit.fclib: {e}")

view raw JSON →