ABQ-FLOW
Modular batch-processing framework for Abaqus FEA based on python. Typed job specs, strategy-pattern workflows, fault-tolerant parallel execution, resource-aware scheduling — no more hand-crafted launch scripts.
English | 简体中文
Features
- ⚒️ Strategy-pattern workflows: compose preparation, extraction, and simulation steps into reusable pipelines
- 📗 Typed configuration:
JobSpecdataclasses validate before execution, no silentKeyErrorat runtime - 🔒 Fault-tolerant parallel execution:
ProcessPoolExecutor+JobOutcomeenvelope; one failed job won't kill the batch - 💻 Extensible: register custom preparation strategies without modifying framework code
Architecture
Installation
Install from PyPI:
pip install ABQflow
If you want the optional abqpy integration path:
pip install "ABQflow[abqpy]"
If you manage environments with Pixi:
pixi add --pypi ABQflow
Prerequisites: Abaqus (with abaqus on PATH), Python ≥ 3.9. abqpy is optional and only needed when you want to run eligible scripts through plain python instead of the Abaqus kernel.
Packaging
Build a source distribution and wheel locally with:
python -m build
Then upload the artifacts from dist/ to TestPyPI or PyPI.
How to use?
Single parameterized job
from ABQflow import BatchAbaqusProcessor, JobSpec, PreparationSpec, HookSpec
spec = JobSpec(
job_name = "planar_stress_odb",
workflow = "modular",
preparation = PreparationSpec(
kind = "inp_based",
source_path = "./examples/cae_file/planar_stress_template.inp",
params = {
"youngs_modulus": 210000,
"load_magnitude": 2000,
}
),
post_extraction = [
HookSpec(
script_path = "./examples/extraction_scripts/get_max_stress_mises.py",
tasks = [
{"result_name": "max_stress_mises",},
{"result_name": "max_displacement",},
]
)
]
)
processor_odb = BatchAbaqusProcessor(
batch_data = [spec],
base_output_dir = os.path.join(CWD, "examples/01_SingleParameterizedJob/output"),
cpus_per_job = 4,
duplicate_mode = "overwrite",
abaqus_exe = ABAQUS_CAE,
)
outcomes = processor.run_batch(num_parallel_jobs=1)
for oc in outcomes:
print(f"{oc.job_name}: {oc.status} → {oc.results}")
Batch parameterized job
import numpy as np
from ABQflow import BatchAbaqusProcessor, JobSpec, PreparationSpec, HookSpec
from ABQflow import generate_from_array, degenerate_from_array
param_names = ['youngs_modulus', 'load_magnitude']
param_values = np.array([
[200000, 2000],
[210000, 3000],
[220000, 4000],
[230000, 5000]
])
base_job_spec = JobSpec(
job_name = "planar_stress_multiple",
workflow = "modular",
preparation = PreparationSpec(
kind = "inp_based",
source_path = "./examples/cae_file/planar_stress_template.inp",
),
pre_extraction = [
HookSpec(
script_path = "./examples/extraction_scripts/get_total_mass.py",
tasks = [
{"result_name": "total_mass",},
]
)
],
post_extraction = [
HookSpec(
script_path = "./examples/extraction_scripts/get_max_stress_mises.py",
tasks = [
{"result_name": "max_stress_mises",},
{"result_name": "max_displacement",},
]
)
]
)
spec_list = generate_from_array(
samples_array = param_values,
param_names = param_names,
base_spec = base_job_spec
)
processor = BatchAbaqusProcessor(
batch_data = spec_list,
base_output_dir = os.path.join(CWD, "examples/02_BatchParameterizedJob/output"),
cpus_per_job = 12,
duplicate_mode = "overwrite",
abaqus_exe = ABAQUS_CAE,
)
outcomes = proc.run_batch(num_parallel_jobs=2)
# Get a 2D numpy array of results
arr = degenerate_from_array(outcomes = outcomes, output_names = ["total_mass", "max_stress_mises", "max_displacement"])
print(arr) # shape (4, 3)
Monolithic script
TODO
Hook Scripts
Extraction hooks run under the Abaqus Python interpreter (abaqus python or abaqus cae noGUI). ABQflow provides hookkit — a single-file, stdlib-only harness that eliminates all boilerplate. You write only the physics.
Quick start (ODB)
# my_extract.py
import os, sys
sys.path.insert(0, os.getcwd()) # hookkit is staged here by ABQflow
import hookkit
def extract_one(odb_path, task):
"""Physics in, value out. Raise on failure."""
from odbAccess import openOdb
name = task['result_name']
with hookkit.opened(openOdb(path=odb_path, readOnly=True)) as odb:
step = odb.steps[task.get('step', list(odb.steps.keys())[-1])]
frame = step.frames[-1]
asm = odb.rootAssembly
if name == 'max_stress_mises':
vals = frame.fieldOutputs['S'].getSubset(
region=asm.elementSets[' ALL ELEMENTS']).values
return hookkit.scalar(max(v.mises for v in vals))
raise ValueError("unsupported result_name: %s" % name)
if __name__ == '__main__':
hookkit.run(extract_one, source_arg='--odb_path')
Quick start (INP / mdb)
# my_mass_extract.py
import os, sys
sys.path.insert(0, os.getcwd())
import hookkit
def extract_one(inp_path, task):
from abaqus import mdb
name = task['result_name']
mdb.ModelFromInputFile(name='_hook_temp', inputFileName=inp_path)
if 'Model-1' in mdb.models:
del mdb.models['Model-1']
root_assembly = mdb.models['_hook_temp'].rootAssembly
region = root_assembly.sets['ALL'].elements
if name == 'total_mass':
mass = root_assembly.getMassProperties(regions=region)['mass']
return hookkit.scalar(mass)
raise ValueError("unsupported result_name: %s" % name)
if __name__ == '__main__':
hookkit.run(extract_one, source_arg='--inp_path')
Field output (large data → CSV sidecar)
For field quantities (stress tensors, displacement fields), use hookkit.field():
def extract_one(odb_path, task):
from odbAccess import openOdb
name = task['result_name']
with hookkit.opened(openOdb(path=odb_path, readOnly=True)) as odb:
frame = odb.steps['Step-1'].frames[-1]
if name == 'stress_field':
vals = frame.fieldOutputs['S'].values
rows = [[v.elementLabel, v.mises] for v in vals]
columns = task.get('columns', ['element_label', 'mises_stress'])
return hookkit.field(task, rows, columns)
raise ValueError("unsupported result_name: %s" % name)
Three output modes, controlled by "output" in the task dict:
"output" |
Behavior |
|---|---|
"inline" |
Return through stdout JSON (always) |
"file" |
Write CSV + return a lightweight envelope (always) |
| (unset) | Auto: >10k rows or >1MB → file, else inline |
Mode is declared in the Spec — the hook script stays the same:
HookSpec(
script_path = "./hooks/get_stress_field.py",
tasks = [{"result_name": "stress_field", "output": "file"}]
)
Task dict reference
Your hook receives tasks as task dicts. Only result_name is required; every other key is user-defined and read by your extract_one via task.get().
| Key | Required | Used by | Purpose |
|---|---|---|---|
result_name |
yes | hookkit + your code | Result key in the output dict; file name for sidecar CSV |
output |
no | hookkit.field() |
"inline" / "file" — controls field representation |
step |
no | your code | ODB step name (e.g. task.get('step', 'Step-1')) |
columns |
no | your code + hookkit.field() |
CSV column headers for field output |
| (any other) | no | your code | Freely defined — hookkit passes everything through transparently |
License Token Planning
from abaqus_batch_pack import solver_tokens, plan_parallelism
# Tokens for 4 CPUs: ceil(5 * 4^0.422) = 9
print(solver_tokens(4)) # → 9
# With 45 license tokens available, 4 CPUs/job (9 tokens each): capped to 5
print(plan_parallelism(requested=8, cpus_per_job=4, license_tokens=45)) # → 5
# With no license limit, CPU cores are informational only — oversubscription
# is allowed, but logs a warning if it exceeds physical core capacity.
print(plan_parallelism(requested=8, cpus_per_job=4)) # → 8 (+ warning)
Formula: T(n) = ⌈5 × n^0.422⌉ (Abaqus official). License tokens are a hard
cap — Abaqus refuses to start a job it cannot license. CPU cores are not:
requesting more parallel jobs than physical cores support is allowed, since
small jobs rarely saturate a full core; it only triggers a warning.
License
MIT License | See LICENSE for more details
Metadata
Release files for ABQflow 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| abqflow-0.5.0.tar.gz | 1.6 MB | With provenance | Details for abqflow-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| abqflow-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for abqflow-0.5.0-py3-none-any.whl |
Total release size: 1.6 MB
Release files / abqflow-0.5.0.tar.gz
| Download URL | abqflow-0.5.0.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
11e959812b2b17b6815c4a685749f64d64d20c8ab8399b4102ecb5eb4ca237ba
|
|
BLAKE2b-256 checksum How to use checksums |
328396d3b02bc8287352dc99cb1e15bc4de0d53b315a124d9b4d17217d43f420
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 5, 2026.
Transparency logRelease files / abqflow-0.5.0-py3-none-any.whl
| Download URL | abqflow-0.5.0-py3-none-any.whl |
|---|---|
| Size | 56.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
95e991e672abba595b93db56e0dad685299debbb4f9e9403f0369a45fdac289f
|
|
BLAKE2b-256 checksum How to use checksums |
2fbe56647c3a5142f6c2136f628ac61c82602e8d63b35ae1b9d15272dfa709a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 5, 2026.
Transparency logSecurity for ABQflow 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for abqflow-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.