Skip to main content

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.

License Version python

English | 简体中文

Features

  • ⚒️ Strategy-pattern workflows: compose preparation, extraction, and simulation steps into reusable pipelines
  • 📗 Typed configuration: JobSpec dataclasses validate before execution, no silent KeyError at runtime
  • 🔒 Fault-tolerant parallel execution: ProcessPoolExecutor + JobOutcome envelope; 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)

Source distribution for ABQflow 0.5.0
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)

Table of built distributions (wheels) for ABQflow 0.5.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page