## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# 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:

Slot | Material
--- | ---
`*MAT_USER_1` | Example metal plasticity
`*MAT_USER_2` | Example concrete compaction and damage
`*MAT_USER_3` | Example Mooney-Rivlin rubber
`*MAT_USER_4` | Example orthotropic composite
`*MAT_USER_5` | Example glass damage

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