Milestone 9 — GT-Suite import completeness

A coverage-driven companion to Milestones 7 + 8, this time targeting AVL Cruise M's biggest competitor: AVL / Gamma Technologies' GT-POWER / GT-SUITE. The acceptance criterion for each phase is "this GT-Suite element type imports cleanly into a runnable aeolus1d case."

Update 2026-07: the importer-side phases 9a–9g and the Tier-1 path of 9h have since landed and this roadmap is now a historical record of the plan rather than open backlog. The .gtsub recursion (9a), engine-breathing template ids (9b), EndEnvironment / ambient-BC resolution (9c), the split lookup-table family (9d, lookup_table_thermal / lookup_table_material), orifice + valveconn translation (9e), and controller silent-skip / lossy reporting (9g) live in src/aeolus1d/io/interop/gt_suite_native.py; the .cmp / .trb map readers (9f) live in src/aeolus1d/io/interop/gt_maps.py. Two details differ from the plan below: the .cmp / .trb maps turned out to be ASCII "GT-Wide" tables (v7.x / v2016), not the binary formats anticipated in 9f (multi-rack NUMRACK > 1 VGT maps still deferred), and 9h shipped only the Tier-1 3-zone prescribed-T option (Cylinder.T_head / T_liner / T_piston in src/aeolus1d/components/cylinder.py) — the Tier-2 radial-conduction solver is still unbuilt. The per-phase effort / risk / done-when notes below are preserved as originally written.

The driver case

The plan is calibrated against a representative user-supplied production heavy-duty diesel GT-Suite case. The fixture files themselves carry vendor / engine-program IP and are not bundled with the repo; the case is dropped into a local folder at the repo root (gitignored) and the integration tests skip cleanly when the folder is absent. Stats observed via aeolus1d inspect-gtm on that case:

• GT version 2017.3.x
• Total parts (resolved): ~940
• Top-level .gtm parts: ~260 (~70 % live in .gtsub sub- templates)
• ~70 distinct templates
• ~275 connection edges
• Contains: 13-cylinder block, twin VGT, DOC + SCR + DPF aftertreatment chain (CatalystBrick + ParticulateFilter + catalysed regenerative trap), charge-air cooler trio, engine controllers (FMEPcalc, HTCcalc, fuel rail / SOI / exhaust-brake / throttle / wastegate controls), 3D FEM cylinder-wall mesh (~5800 nodes / ~3700 elements).

Today's gt_suite_native importer pulls ~60 pipes + ~145 junctions + ~12 wall BCs from the top-level — a parseable skeleton, but the ParticulateFilter, CatalystBrick, Cylinder, Turbocharger, Compressor, Charge-Air Cooler, and controller bus are all dropped or misclassified.

Scope boundary. The 3D FEM cylinder-wall mesh, the controller bus, wall lubricant loops, and bearing-friction torque models are explicitly out of scope — they belong in a coupled-simulation flow (Phase 7e FMI export) or remain dropped with explicit warnings.

Importer-side gaps (aeolus1d.io.interop.gt_suite_native)

These phases are pure plumbing — extending the importer to recognise additional GT-Suite template ids and pull the right parameter values into the aeolus1d models that already exist.

Phase 9a — .gtsub sub-assembly resolution

Goal. Recursively follow <gtsub> sub-assembly references in the top-level .gtm, load each .gtsub file (same XML schema, just rooted at a sub-template), and merge the parts / links into one unified Schematic. This is already in BACKLOG.md; promoting to Phase 9a because it's the single biggest gap — without it ~70 % of the parts in a typical production case are invisible to the importer.

Approach. Walk the top-level .gtm's reference list, resolve relative paths against the .gtm's parent directory, recursively load each .gtsub (cycle-detect via a visited set), merge the parts / links / parameter tables. The Windows-style absolute paths in saved references need rewriting to be relative.

Effort. ~3-4 days.

Risk. Medium. Circular sub-assembly refs need cycle detection; missing .gtsub files in the user's folder need a clean error message + best-effort partial import.

Done when. The driver case's resolved model imports with the part count matching the .out file's "Total Number of Parts" line (modulo lossy elements that intentionally get skipped).

Phase 9b — Engine breathing-path template parsing

Goal. Recognise the GT-Suite template ids for engine internals: cylinder, valve, injector, compressor, turbine, shaft. The _TEMPLATE_PARAM_LAYOUT table in gt_suite_native.py needs entries for each template's <va a_id> parameter layout. Already partially in BACKLOG.md.

Mappings:

GT-Suite template	aeolus1d model
Cylinder block (multi-cylinder template)	Cylinder (slider-crank)
Cylinder geometry sub-template	CylinderSpec bore/stroke/clearance
Poppet valve	CylinderPort valve windows
Injector	injection schedule on Cylinder (multi-injector after Phase 8c lands)
Turbine	Turbine with TurboMap
Compressor	Compressor with TurboMap
Shaft	Shaft

Effort. ~5-7 days. Per-template <va> layouts vary across GT-Suite versions; tedious but mechanical work.

Risk. Medium. The <va> parameter layout is GT-Suite's internal serialisation; without their schema docs we reverse-engineer per template. Wrong layout → silently wrong parameter values. Mitigation: cross-validate against the .out file's resolved parameter table when the importer finishes.

Done when. The driver case imports with all of its cylinder / compressor / turbine / shaft instances populated, each carrying their geometry + schedules + map data.

Phase 9c — EndEnvironment auto-attach + parameter blocks

Goal. GT-Suite EndEnvironment objects (~4 in the driver case, paired forward / reverse on the exhaust side) reference initial-state parameter-block objects via the <va> text fields (AmbState, HPstate). Resolve these to numeric pressures + connect them to the right pipe ends — replaces the synthesised wall BCs with real stagnation_inlet / pressure_outlet BCs. Already in BACKLOG.md.

Effort. ~1-2 days once Phase 9a (.gtsub resolution) lands — the parameter blocks may live in a sub-template.

Done when. EndEnvironment-derived wall BCs become real ambient BCs; the imported case mass-flows through realistic ambient T + p instead of being capped by walls.

Phase 9d — Lookup-table → closure dispatch

Goal. GT-Suite's lookup_table objects (~14 in the driver case, sample names: avgport, inport, steelwall, cachcond) feed into heat-transfer / friction / cylinder-wall closures. Map them onto aeolus1d's table-driven closures: tabulated viscosity, pipe friction with Re-dependence, cylinder wall T(crank-angle), etc.

Mappings:

Lookup-table use	aeolus1d equivalent
avgport, inport (port heat-transfer correlation)	heat closure with table input
steelwall (wall material thermal conductivity)	wall-conduction model (Phase 9h)
cachcond (charge-air cooler conduction)	heat-exchanger ε-NTU (Phase 8d)

Effort. ~2-3 days. Most of the work is identifying which lookup-table feeds which closure based on <connect> edges in the .gtm.

Done when. Imported pipes carrying GT-Suite lookup- tabled friction / heat closures use the table values rather than constant defaults.

Phase 9e — Orifice + valveconn → BC translation

Goal. orifice (~15 in the driver case) and valveconn (~4) templates map to aeolus1d's valve_orifice BC kind or intra-pipe pressure-drop closures. The names give the intent: exhaust brake (controlled-area orifice between two pipes), muffler (passive restriction), general orifices, valve-connectors.

Effort. ~1-2 days.

Done when. Orifice / valveconn parts in the driver case become explicit BC objects rather than getting dropped to lossy_components.

Phase 9f — Compressor .cmp + Turbine .trb map readers

Goal. GT-Suite cases routinely carry binary compressor maps (.cmp) and turbine maps (.trb) alongside the .gtm. aeolus1d today supports synthetic + learned-NPZ turbo maps; these binary AVL formats need reader functions that produce the same TurboMap shape.

Approach. New aeolus1d.io.interop.gt_suite_native helpers _read_cmp_map(path) and _read_trb_map(path) returning a populated TurboMap. The .cmp / .trb formats are AVL's own; structure inferred via hex-dump and GT-Suite docs (some .cmp readers exist in open-source GT-POWER post-processing tools).

Effort. ~3-4 days. Format reverse-engineering is the unknown; if the formats turn out to be standardised (.cmp = SAE J1826 compressor map; .trb = similar) the work collapses to ~1-2 days.

Done when. The driver case's compressor + turbine import with map data lifted from the .cmp / .trb files rather than the importer's synthetic-default fallback.

Phase 9g — Controller / control-signal silent-skip + lossy reporting

Goal. GT-Suite's controller framework (~15 control_signal + ~7 monitor + ~6 param + ~2 controller + ~2 control parts in the driver case) has no aeolus1d analogue and no plan to add one — engine- control logic belongs in a coupled-simulation tool that drives aeolus1d via FMI. Surface as warnings naming each control sub-assembly so the user sees what's been dropped.

Approach. Same shape as Phase A24's audit-trail warnings for Cruise M. Map each control template id to "silently skipped" with a per-template warning; map controller / control to the lossy list.

Effort. ~1 day. Mostly enumeration + warning text.

Done when. The driver case's import report names every controller sub-assembly + recommends Phase 7e (FMI export) as the integration path.

Aeolus feature gaps

These overlap heavily with Milestone 8; this section serves as cross-reference. The driver case specifically needs:

• Phase 8c — multi-injector cylinders — case-data parameters describing per-injection rates per cycle.
• Phase 8d — heat-exchanger ε-NTU — the charge-air cooler trio (CACPipe / CACOutPipe / CACInPipe).
• Phase 8f — DPF — the catalysed regenerative trap part modelled as a ParticulateFilter.
• Phase 8g — VGT — twin VGT actuators on the turbocharger.
• Phase 8i — particulate matter species column — needed by the DPF.

Phase 9h — Cylinder wall thermal-conduction model (GT-Suite specific)

Goal. GT-Suite models cylinder-wall heat transfer with a multi-zone wall-conduction model (DL-CylTWallSoln + WallTemperatureMethod — "Imposed Wall or Calculated Wall Temperature"). aeolus1d today has per-cell T_solid arrays for catalyst pipes (Phase 15 two-phase heat transfer) but no cylinder-wall multi-zone conduction. The cylinder runs effectively adiabatic or with the simpler WoschniHeatTransfer / HohenbergHeatTransfer single-T_wall correlation (Phase 25h scope).

Approach. Two implementation paths:

1. Tier-1: a 3-zone cylinder wall (head, liner, piston crown) with prescribed steady T per zone. ~1 week.
2. Tier-2: a 1-D radial wall-conduction solver per zone with Calculated Wall Temperature (the GT-Suite default for production engine models). ~2-3 weeks; closer to GT-Suite's behaviour but adds a second ODE state per cylinder.

Effort. Tier-1 ~1 week; Tier-2 ~2-3 weeks. Pick Tier-1 first — covers most production models — and promote to Tier-2 only if the per-zone T resolution matters.

Risk. Low for Tier-1; medium for Tier-2 (the radial solver couples to the gas-side timeloop and needs stability checks).

Done when. The driver case imports with 3-zone cylinder walls (T_head / T_liner / T_piston) populated from the project's lookup tables; cycle-resolved heat-transfer matches GT-Suite's calculated wall-T values to ~5 %.

Out-of-scope items — go through FMI

Phase 9z — Shared with Phase 7e / 8z (FMI export)

The 3D FEM cylinder-wall mesh, the control sub-assemblies (fuel-rail / SOI / FMEPcalc / HTCcalc / exhaust-brake / throttle / wastegate controllers), the bearing-friction torque model, the lubricant-flow loop, and the vehicle-side (drivetrain, thermal management, hybrid drive) live outside aeolus1d's scope. Same FMI-export path as Milestone 8's Phase 8z.

Summary

Phase	Effort	Cumulative	Driver-case coverage delta
9a — .gtsub sub-assembly resolution	3-4 d	4 d	+~680 parts (~70 % of model)
9b — engine breathing template parsing	5-7 d	11 d	cyls + compressors + turbines + shaft
9c — EndEnvironment auto-attach	1-2 d	13 d	ambient BCs (replaces wall fallbacks)
9d — lookup-table closure dispatch	2-3 d	16 d	lookup tables wired to closures
9e — orifice + valveconn translation	1-2 d	18 d	exhaust-brake + muffler + misc
9f — .cmp + .trb map readers	3-4 d	22 d	calibrated turbo maps
9g — controller silent-skip + warnings	1 d	23 d	control sub-assemblies surfaced
9h — cylinder wall thermal conduction	1 w (T1) / 2-3 w (T2)	30-44 d	multi-zone wall T per cylinder

~6-9 weeks of M9-specific work. Plus ~12-16 weeks of Milestone 8 work whose physics the driver case also needs (CAC, DPF, VGT, multi-injector, PM species).

If both M8 and M9 ship: a representative production heavy- duty diesel GT-Suite case imports cleanly as a runnable aeolus1d case for the breathing-path + aftertreatment sub- systems. The control / FMEPcalc / HTCcalc / vehicle / 3D-FEM stays out of scope and routes through Phase 7e FMI co- simulation.

Cross-reference

• GT-Suite native .gtm import lives in the source tree at src/aeolus1d/io/interop/gt_suite_native.py. The XML-format GT-Power importer (src/aeolus1d/io/interop/gt_power.py) is a separate code path — older GT-POWER releases that save XML rather than .gtm. Both share aeolus1d.io.interop.schematic for the neutral schema.
• Milestone 8 (milestone-8-cruise-import-completeness.md) covers the same physics targeted at AVL Cruise M imports. Phases 8c-8i are shared; M9-specific phases (9a-9h) are GT-Suite-format work.
• Milestone 7 (in phase-log.md) covers the same physics from a feature-driven angle. Each Milestone 9 phase that depends on new aeolus1d physics points at the matching M7 sub-phase.