ENSIMA

AI-driven parameter optimization for metal stamping simulations

Report Bug · Request Feature

ensima is the optimization component of the ENSIMA project. It applies Bayesian optimization with Gaussian Process Regression to accelerate design parameter selection in sheet metal forming simulations, reducing the number of costly simulation runs needed to find optimal process parameters.

Overview

ensima provides tools for optimizing and managing parameter selection for stamping simulations. Key features include:

• Bayesian Optimization with Gaussian Process Regression (GPR) backend supporting both PyTorch and scikit-learn
• Mixture of Experts (MoE) with PointNet geometry encoding for multi-part optimization
• Acquisition functions: Expected Improvement (EI), Human-Guided Active Learning (HGAL)
• End conditions: no improvement, constant minimum, energy budget
• HPC support: cluster-aware argument adjustment, license server management, energy monitoring
• Multi-objective optimization with Pareto frontier analysis

For a full breakdown of the repository structure and file descriptions, see files.txt. Detailed documentation (architecture, design concepts, usage, contributing) is available in doc/.

Installation

To install ensima in a virtual environment, use the Makefile:

make install

This will:

1. Create a virtual environment in .venv.
2. Install ensima in editable mode with optional dependencies.

To install optional libraries (ruff, black, nbstripout, numba, etc.):

make debug

Activating the Virtual Environment

After installation, activate the virtual environment with:

source .venv/bin/activate

Adapting to Your Environment

Running ensima against real simulations requires pointing it at your local installations of OpenForm and OFSolve and at a valid RLM license server.

Note: Without --openform and --ofsolver, ensima falls back to the built-in dummy objective function, which is sufficient for testing the optimization loop but does not run any real simulation.

The recommended approach is to pass all paths directly to parse_arguments(), as shown in examples/example_filtered_optimization_cluster.py:

args = parse_arguments([
    "-ofs", "/path/to/OFSolv_1.0.4e_eng_linux64.exe",
    "-ofm", "/path/to/OpenForm_64_batch",
    "-p",   "/path/to/TCO-Benchmark/PartType_04",
    "-o",   "/path/to/output/results.csv",
    "--license_server",         "your-license-server",
    "--license_port",           "your-port",
    "--license_type",           "RLM",
    "--license_server_service",
    ...
])

Replace every path and the license server address with the values that apply to your machine or cluster. Because the paths are passed explicitly, they override any defaults and no further adaptation is needed.

Alternatively, ensima/helpers/adjust_args_cluster.py provides a helper that rewrites paths and license settings based on the machine's hostname, as shown in examples/example_moe_optimization.py. Both approaches are equivalent — the hostname-based helper only makes sense if you want a single script to run unchanged across multiple known machines.

⬆

Usage

Once installed, you can use the command-line tool:

ensima -h

Command-Line Arguments

Argument	Short	Type	Default	Description
--ofsolver	-ofs	str	None	Path to the OpenFOAM solver executable.
--jobname	-j	str	None	Name of the optimization job.
--path	-p	str	"./"	Path to job directory.
--output	-o	str	None	Output directory or filename for results.
--cores	-c	int	4	Number of CPU cores allocated.
--openform	-ofm	str	None	Path to the OpenForm software.
--session	-s	str	None	OpenForm session file.
--plot	-pl	flag	False	Enable plotting of results.
--iterations	-it	int	20	Number of optimization iterations.
--parallel_samples	-ps	int	1	Number of parallel samples per iteration.
--energy_estimation	-e	flag	False	Enable energy estimation.
--method	-m	str	bo	Optimization method (bo, hgal).
--end_condition	-ec	str	no_improvement	Termination condition (no_improvement, constant_min, energy_budget).
--end_value	-ev	float	5	Threshold for the end condition.
--x_fields	-x	str+	["Rp","D","p","Fr","db"]	Input parameter field names.
--y_fields	-y	str+	["L1","L2","L3","L4","L5","L6"]	Output field names.
--log_level	-l	str	INFO	Logging level.

Example Usage

Run with a dummy objective function (no simulation required):

ensima

Run with custom parameters:

ensima --ofsolver /path/to/solver --openform /path/to/openform \
  --jobname "OptimizationJob" --path /path/to/job \
  --cores 8 --session session.ofs --iterations 30 --parallel_samples 2 -e

Energy Budget End Condition

ensima --iterations 40 -e --end_condition energy_budget --end_value 0.8

No Improvement Condition

ensima -it 40 --end_condition no_improvement --end_value 3

Constant Minimum Condition

ensima -it 40 --end_condition constant_min --end_value 3

Using the Optimization in a Python Script

from ensima.helpers.parse_args import parse_arguments
from ensima.classes.bayesian_optimization import BayesianOptimization
import numpy as np

def dummy_objective_function(x):
    return np.sin(x).sum(axis=1).reshape(-1, 1)

args = parse_arguments(["--jobname", "PythonOptimization", "--iterations", "10"])

x_init = np.random.rand(5, 1) * 10
y_init = dummy_objective_function(x_init)

optimizer = BayesianOptimization(
    x=x_init, y=y_init, args=args, objective_function=dummy_objective_function
)
optimizer.optimize(n_iters=args.iterations)

⬆

Testing

A test suite is provided under test. Run all tests with:

cd test && make

Or silently:

cd test && make silent

To run a specific test directly:

cd test && python3 test_optimization.py

⬆

Examples

Several examples are provided under examples:

Script	Description
example_optimization.py	Basic single-part Bayesian optimization
example_moe_optimization.py	Multi-part optimization with Mixture of Experts
example_expert.py	Expert-based filtered optimization
example_filtered_optimization_cluster.py	Filtered optimization on an HPC cluster
example_train.py	Training a GP model on benchmark CSV data
example_train_subset.py	Training on a filtered subset
example_detailed_training.py	Detailed GP training walkthrough
example_plot.py	Plotting optimization results

Experiment data and results used for the JIMS paper are available under artifacts/JIMS, organized by experiment type (MLVGP, MOE, no_optimization) and part geometry.

⬆

Contributing

Contributions are welcome. Please open an issue or submit a pull request on GitHub.

⬆

Contact

• Ahmad Tarraf — ahmad.tarraf@tu-darmstadt.de

⬆

License

Distributed under the BSD 3-Clause License. See LICENSE for more information.

⬆

Acknowledgments

The optimization loop in ensima is developed and maintained by the Parallel Programming group at TU Darmstadt. The main author of the optimization loop is Ahmad Tarraf.

This software is part of the ENSIMA project, funded by the German Federal Ministry of Research, Technology, and Space (BMBF), grant period 2022–2025. The project aims to accelerate design parameter optimization in sheet metal forming through AI-based methods, approximate computing, and heterogeneous hardware.

⬆