Headless circuit authoring: submodels, search paths and initial states

Five things that stop a circuit built through ame_apy from building, or make it run from the wrong starting point, without an error at the moment the mistake is made. All were EXERCISED on Simcenter Amesim 2511 on 2026-09-24 while building the QX-250 function models, and the amesim MCP tools now handle each one.

1. Icons with several submodels are placed with no submodel

AMEAddComponent sets the submodel automatically only when the icon has exactly one. Icons such as eb_BatPackSimple, controlled_currentsource and signalsink have several, so the component is placed with no submodel and the circuit cannot generate code.

Set it with AMEChangeSubmodel(alias, submodel, directory), for example AMEChangeSubmodel("BT1", "EBBATPSQS01", "$AME/libeb/submodels"). In ame_apy this takes three arguments. A five-argument form belongs to the GUI's scripting module and raises TypeError here.

The MCP tools: amesim_add_component(..., submodel=...) or amesim_set_submodel(alias, submodel). Both read the circuit back and report success only when the component carries the requested submodel.

2. The headless search path can leave out an installed library

A headless session's paths list did not include $AME/libemd, so placing emd_DirectCurrentMachine failed with "unknown icon. Icon not found in paths list" although the library is installed.

Fix: AMEAddPathToPathsList("$AME/libemd", position), then confirm with AMEGetPathsList(). amesim_add_component now finds which library declares the icon, adds it, confirms it and retries once, reporting the added path. A name no library declares still fails, and says so.

3. The submodel index can miss submodels that are installed

AMEOpen's findElementFromSubmodel answered "Element not found" for EBBATPCV01 and EBBATPSQS01, although openSubmodel resolves them, the eb_BatPackSimple icon lists them, and they build and run. EBR01 in the same library resolved normally.

Do not read "not found" from that call as "not installed". amesim_lib_submodel now falls back to opening the submodel directly and finds its icon by scanning the library categories; it reports which lookup answered and the submodel directory.

4. Initial states are not in the parameter list

A state variable with a start value is set like a parameter but is not iterated by the parameter flags. A battery's initial state of charge, soc@BT1, defaults to 60 %, and a thermal node's initial temperature t1@ambient defaults to 20 degC. A run that never sets them starts from those defaults with no warning: one QX-250 run started 40 points of charge low.

amesim_list_parameters now makes a second pass with the start-value flag and lists these with scope: state_initial_value.

5. A failed setup step turns into a write on the active circuit

Most ame_apy calls act on "the active circuit". If creating a new circuit fails (a name containing a hyphen is refused as "invalid circuit name"), later calls act on whatever circuit was open before and AMESaveCircuit writes to it. This damaged a real model once during testing; it was restored and verified against version control.

Test scripts must stop at the first failed step, and scratch circuits need a plain name with no hyphens.

Also

• Build helpers (the gcc link and the Java file-upload helper) now start without a console window, after console windows were seen appearing on the desktop during builds. The change is applied; the desktop effect has not been re-observed.