gepfoam

gepfoam is a tensor-based gene expression programming (TB-GEP) package for symbolic model discovery from data. It provides scikit-learn-style estimators for scalar regression, dimensional regression, and tensor-basis regression, supporting scientific workflows in which model structures, constants, and tensor coefficients are inferred from tabular datasets.

The package was originally developed for turbulence-model discovery with OpenFOAM-based computational fluid dynamics (CFD) evaluations. This public release focuses on the offline TB-GEP model-discovery and regression components only. It does not require OpenFOAM, and external simulation coupling or CFD solver-in-the-loop evaluation is not included in this release.

TB-GEP extends the usual fixed-length GEP chromosome with a modular tensor representation. Plasmid genes discover nondimensional scalar modifiers; host genes define tensor-basis or dimensional basis structure; and, when used, a homeotic gene controls how host-gene outputs are assembled into the final symbolic expression. This separation lets the search evolve compact expressions for tensorial and dimensional quantities while retaining the syntactic validity and genetic-operator structure of GEP.

What It Provides

• GEPRegressorScalar for scalar symbolic regression, including nondimensional or dimensional scalar regression when the user supplies the corresponding input features.
• GEPRegressorTensor for tensor-basis symbolic regression and dimensional regression, such as discovering tensorial or dimensional closure corrections from scalar features and tensor-basis or dimensional basis columns.
• Offline evolutionary search with optional local optimization, linear scaling, symbolic simplification, checkpointing, and expression-tree visualization.
• Public fitness metrics:
  • nmse: normalized mean squared error, minimized directly.
  • r2: coefficient of determination, internally minimized as -R2.

Local optimization currently supports single-objective offline regression. Multi-case and Pareto-aware local optimization are planned for a future version; multi-case NSGA-II workflows should use evolutionary search without local optimization in this release.

When NMSE is normalized by the target variance under the same convention used for R2, NMSE = 1 - R2. This makes nmse and r2 consistent while keeping the optimizer convention that smaller fitness values are better.

Install

Use the provided conda environment from the repository root:

conda env create -f environment.yml
conda activate gepfoam
python -m pip install .

The first command creates an environment with the required third-party dependencies. The final python -m pip install . command installs gepfoam itself into that environment, so import gepfoam works from any directory.

Graphviz is required to render expression-tree PDFs. If Graphviz is unavailable, the package still writes the DOT source file for the tree.

Quick Start

import numpy as np
from gepfoam import GEPRegressorScalar

rng = np.random.default_rng(42)
X = rng.uniform(-1.0, 1.0, size=(200, 2))
y = 0.5 * X[:, 0] - 1.2 * X[:, 1] ** 2 + 0.3

est = GEPRegressorScalar(
    population_size=50,
    generations=5,
    n_genes=1,
    head_length=5,
    function_set=("add", "sub", "mul", "_protected_div"),
    metric="nmse",
    LOCAL_OPTIMIZER=False,
    LINEAR_SCALING=False,
    random_state=42,
    verbose=0,
    write_files=False,
)

est.fit_scalar(X, y)
y_pred = est.predict(est._program_alone, X)
print(est.simplify(est._program_alone))

Checkpointing

For long offline runs, checkpoints can be saved explicitly and resumed later. The demos keep warm_start=False for reproducibility, but the package exposes the utility for larger experiments:

params = dict(
    population_size=50,
    generations=5,
    n_genes=1,
    linker=None,
    head_length=5,
    function_set=("add", "sub", "mul", "_protected_div"),
    checkpoint_dir="checkpoints_scalar",
    warm_start=False,
)

est = GEPRegressorScalar(**params)
est.fit_scalar(X, y)
checkpoint_path = est.save_checkpoint()

resumed = GEPRegressorScalar(**{**params, "warm_start": True})
resumed.fit_scalar(X, y)

If checkpoint_dir is omitted, checkpoints are stored under the estimator's offline reporting directory.

Examples

Example scripts live under examples/demo/:

• scalar_regression/: scalar symbolic regression from tabular data.
• polynomial_regression/: synthetic polynomial scalar regression.
• dimensional_regression/: dimensional-basis regression using user-provided scalar features and dimensional basis columns.
• tensorial_regression/: tensor-basis regression.
• nsga2/: multi-case tensor-basis regression with one Pareto objective per case.

Documentation

• Architecture and scope explains the TB-GEP representation, estimator layout, metric conventions, tensor-basis input shapes, and release boundaries.
• TB-GEP diagrams from the paper are included under docs/assets/.

Relationship To geppy

The internal GEP backbone is related to and partly adapted from geppy, while the public workflow is different: this package exposes estimator-style APIs and adds tensor-basis and dimensional scalar regression workflows for offline scientific model discovery. geppy is not a runtime dependency.

See NOTICE for attribution and license compatibility notes.

References

• Ferreira, C. (2006). Gene Expression Programming: Mathematical Modeling by an Artificial Intelligence (Vol. 21). Springer.
• Gao, S., Sun, C., Xiang, C., Qin, K., and Lee, T. H. (2022). Learning asynchronous Boolean networks from single-cell data using multiobjective cooperative genetic programming. IEEE Transactions on Cybernetics, 52(5), 2916-2930. https://doi.org/10.1109/TCYB.2020.3022430

Citation and Acknowledgements

If you find gepfoam or the TB-GEP methodology useful in your research or development work, please consider citing one of the following articles. Citations help others discover the project, reproduce related work, and build on the methods provided here.

• Tian, R., Hickel, S., and Dwight, R. P. (2026). A Bi-Fidelity Framework for Accelerating CFD-Driven Turbulence Model Discovery With Tensor-Based Gene Expression Programming. SSRN. https://doi.org/10.2139/ssrn.6293285

• Tian, R., Hickel, S., and Dwight, R. P. (2026). Multi-Fidelity Turbulence Model Discovery via Partially Converged CFD-in-the-Loop Evaluations. SSRN. https://doi.org/10.2139/ssrn.6881197

These articles describe the broader research workflow behind this project, including CFD-driven and multi-fidelity approaches for turbulence-model discovery. This repository provides the public offline TB-GEP model-discovery component.

We also kindly ask users to acknowledge the geppy lineage described in the NOTICE file.

License

This project is distributed under LGPL-3.0-only. See LICENSE and NOTICE.