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

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.1
File Size Uploaded Provenance Actions
abqflow-0.5.1.tar.gz 380.6 kB With provenance Details for abqflow-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ABQflow 0.5.1
File Interpreter ABI Platform Actions
abqflow-0.5.1-py3-none-any.whl Python 3 none any Details for abqflow-0.5.1-py3-none-any.whl

Total release size: 470.8 kB

Release files / abqflow-0.5.1.tar.gz

Download URL abqflow-0.5.1.tar.gz
Size 380.6 kB
Tags Source
SHA-256 checksum
How to use checksums
87daef75e8410f24842943435366112f4b8af24dd42758dffb11daf84f3fce93
BLAKE2b-256 checksum
How to use checksums
4f56a8338ce5fcb04f3174d2d65abff0c9b69599419e7c593908f130e1964d1f
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 Sep 1, 2026.

Transparency log

Release files / abqflow-0.5.1-py3-none-any.whl

Download URL abqflow-0.5.1-py3-none-any.whl
Size 90.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f660f4b71416197659e73a2f382e1364eabae00bda93729a2736e170c9f233ec
BLAKE2b-256 checksum
How to use checksums
0b42e406780d423712b6354ae84ac3fc73466c3dc3e9c3a0d8a5afba1f6d7f7e
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 Sep 1, 2026.

Transparency log

Security for ABQflow 0.5.1

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.1.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 Sep 1, 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