Native C Backends

How the library achieves high-performance integration.

Python is notoriously slow at tight numerical loops. While NumPy array vectorization helps, fractional solvers require maintaining history buffers and performing sliding convolutions at every time step, which is difficult to vectorize cleanly without massive memory overhead.

To solve this, hidden-attractors-fo uses Just-In-Time (JIT) C compilation.

How it works

When you instantiate a solver (like EFORKSolver) and call .integrate(), the library does the following:

  1. Check for cached binary: It looks in the hidden_attractors/native/bin directory for a pre-compiled shared library matching the solver and OS.
  2. Compile if missing: If not found, it writes a .c file containing the optimized integration loop and invokes your system’s C compiler (gcc or clang).
  3. Load via ctypes: The compiled .so (Linux/macOS) or .dll (Windows) is loaded into the Python process.
  4. Execute: The NumPy arrays containing the initial conditions are passed directly to the C function via memory pointers.

This process is entirely transparent. You do not need to call compilation scripts manually.

OpenMP Parallelization

The C backends are written with OpenMP pragmas. When you pass a batch of initial conditions to .integrate(X0, t_span), the C loop distributes the trajectories across your CPU cores.

For example, integrating 50 trajectories with EFORK on an 8-core machine will take roughly the same amount of time as integrating a single trajectory.

Manual Compilation

If you want to force the library to recompile the backends (e.g., if you changed compiler versions), you can use the internal compilation module:

from hidden_attractors.native.compile import compile_c_target

# Compiles the EFORK backend
compile_c_target("efork")

# Compiles all available targets
compile_c_target("all")

Troubleshooting

If the compilation fails, the library will log a warning and fall back to a pure-Python implementation.

Common issues:

  • Missing gcc: Install build-essential on Linux or MSYS2 on Windows.
  • Missing libomp (macOS): Apple’s clang does not include OpenMP. You must install it via Homebrew (brew install libomp).

See Platform Notes for OS-specific setup instructions.