Manifest and GUI documentation

The example library in this framework is named IMPETUS example user material. It is built from the source in user-material/ and exports five material slots:

The example library carries two kinds of user-facing metadata:

• user-material/manifest.json is embedded into the DLL or shared object at build time.
• doc/IMPETUS example user material.xml is a sidecar file copied beside the built library.

The manifest and XML are used by the GUI to show a friendly material name, creator, description, supported slots, CPU/GPU support, parameter names, parameter descriptions, and example cards. They are not used by the solver while evaluating material response. A simulation can run from the compiled library and input deck even if the GUI metadata is absent, but users lose the friendly selection and documentation experience.

The optional title line on a *MAT_USER_X card should be the base name shared by the user material binary and XML sidecar. For this framework example, the title line is:

"IMPETUS example user material"

The GUI editor uses this title when it looks up the XML documentation for the current *MAT_USER_X command. If the title does not match the DLL/XML base name, the manual panel may not show the correct material documentation when the cursor is on the command.

Manifest

The manifest is JSON and is exported from the binary through impetus_user_material_get_manifest_json. The build generates this export from user-material/manifest.json using tools/embed_umat_manifest.cmake.

Keep the following fields current whenever a material is added, removed, or changed:

• name, version, createdBy, and description describe the package shown by the GUI.
• interface.slots lists the implemented MAT_USER_X slots.
• Each material entry lists slot, command, title, name, description, cpuSupported, gpuSupported, and parameters.
• title should match the binary/XML base name used on the optional title line.
• Each parameter entry lists its card position, p_cmat index, display name, description, required flag, and kind.

mid is the material id and has no p_cmat index. The solver stores the first material value after mid at p_cmat[0]. User parameters that belong to the custom portion of the card normally begin at p_cmat[6], which is the first value on the line after mid,rho,E,nu,did,tid,eosid.

XML sidecar

The XML sidecar uses the userMaterialDocumentation format. Its library attribute must match the binary stem exactly:

<userMaterialDocumentation version="1" library="IMPETUS example user material">

Each <material> entry should match the manifest command and title. Include one <parameter> entry for every visible user parameter, then add a user-facing description, equations when useful, calibration notes, limitations, and complete input examples. The XML should explain the material behavior and expected input; avoid implementation details that do not help a solver user fill the card.

Build output

A Release build copies the binary and sidecar documentation to the build tree:

build/deliverables/Release/IMPETUS example user material.dll
build/deliverables/Release/IMPETUS example user material.xml

On Linux the binary extension is .so.