Skip to content

Docs/readme agents #1049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jginternational merged 2 commits into from
Nov 12, 2026
Merged

Docs/readme agents #1049

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f28bba2
Update README and add AGENTS.md
jginternational Nov 12, 2026
37a7d7b
auditoria
jginternational Nov 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 92 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# AGENTS.md

Guidance for AI coding agents (and humans) working on the Kratos ↔ GiD interface.
For installation and user-facing docs see [README.md](./README.md).

## What this repo is

A GiD *problemtype* (`kratos.gid/`) that lets users build Kratos Multiphysics models in GiD. It writes the Kratos input files (`.mdpa`, `ProjectParameters.json`, materials `.json`) and launches Kratos.

- **Language:** Tcl/Tk on top of GiD's *customlib* framework. Data trees are XML (`.xml`, `.spd`).
- **Python** is used only in `kratos.gid/exec/MainKratos.py`, `scripts/Custom/python_writer.py` and the release tools.
- There is **no standalone build or test command**: the code runs inside GiD.

## Layout

| Path | Purpose |
|---|---|
| `kratos.gid/kratos.tcl` | Entry point: registers GiD events (`GiD_RegisterEvent`, e.g. `GiD_Event_LoadModelSPD`), version checks, model upgrade. |
| `kratos.gid/kratos.xml` | Problemtype metadata: version, `MinimumGiDVersion`, required pip packages. |
| `kratos.gid/kratos.spd` | Root data tree; `<Kratos_data version=…>` and one `appLink` per application. |
| `kratos.gid/kratos.transform` | Rules applied when opening a model saved with a different `.spd` version. |
| `kratos.gid/apps/<App>/` | One folder per application (see below). |
| `kratos.gid/apps/Common/xml/` | Shared definitions (processes, solvers, results, intervals…) reused by apps. |
| `kratos.gid/scripts/Model/` | In-memory model: Element, Condition, Material, Process, Solver… |
| `kratos.gid/scripts/Writing/` | Generic writers for mdpa, submodelparts, materials, ProjectParameters, stages. |
| `kratos.gid/scripts/Controllers/` | Windows: preferences, application market, examples, tree injections. |
| `kratos.gid/scripts/Launch.tcl` | Execution modes (GiD python, pip, local compiled, docker) and dependency checks. |
| `kratos.gid/exec/` | Per-mode, per-OS launch scripts (`*.win.bat`, `*.unix.bat`) and `MainKratos.py`. |
| `kratos.gid/libs/` | Third-party Tcl libs — do not modify. |
| `tools/`, `dockers/` | Release packaging. |
| `dist/` | Release output (git-ignored) — never edit. |

## Anatomy of an application (`apps/<App>/`)

```
app.json id, prefix, kratos_name, python_packages, script_files, start_script,
requirements (apps, minimum_gid_version), permissions, unique_names, write
start.tcl namespace ::<App>; Init stores the app object and calls xml::Init / write::Init
xml/Main.spd Tree for this app (plus Parts.spd, Materials.spd, … included from it)
xml/*.xml Catalogues: Elements, Conditions, Materials, ConstitutiveLaws, Processes, Solvers, Strategies
xml/XmlController.tcl ::<App>::xml — loads catalogues via Model::get*, CustomTree tweaks
write/write.tcl ::<App>::write — mdpa writing (Init sets attributes from app.json)
write/writeProjectParameters.tcl ProjectParameters.json
examples/examples.xml Example list; each <Example cmd=…> points to a proc in examples/*.tcl
images/ Icons and example thumbnails
```

Conventions:
- Every namespace registers itself with `Kratos::AddNamespace [namespace current]`.
- Sub-namespaces use `namespace path ::<App>` to reach the app's helpers (`GetAttribute`, `GetUniqueName`, `GetWriteProperty`).
- Tree node names are prefixed with the app `prefix` (e.g. `STParts`, `FLBC`); use `unique_names` from `app.json` instead of hard-coding them.
- Any new `.tcl` file must be listed in `script_files` of `app.json`, otherwise it is not sourced.
- Reuse `apps/Common/xml/*` and the generic writers in `scripts/Writing/` before adding app-specific code.
- Launcher apps (`FluidLauncher`, `PfemLauncher`, `DEMLauncher`, `ThermicLauncher`) only route to other apps.

### Adding a new application
1. Copy the structure of a similar app (e.g. `Fluid` or `Structural`) to `apps/<NewApp>/`.
2. Choose a unique `prefix` and update `id`, `kratos_name`, `python_packages`, `unique_names`, `start_script`.
3. Add an `appLink` to `kratos.spd` (`public="1"` to show it in the market, `production="1"` to ship it in releases).
4. Add tests in the tester repo (see below).

## Versioning — read before touching versions

The Kratos version (currently `10.4.3`) is hard-coded in several places that must stay in sync:

- `kratos.gid/kratos.xml` — `<Version>` and `<Package … Version=…>`
- `kratos.gid/kratos.spd` — `<Kratos_data version=…>`
- `kratos.gid/kratos.tcl` — `pip_packages_required`
- `README.md` — pip install commands
- `tools/create-release.bat`, `dockers/deploy.bat`, `dockers/create-release.sh`

Search for the old version string across the repo when bumping it.

**Model compatibility:** when a saved model's `.spd` version differs from `kratos.spd`, GiD runs the upgrade defined by `kratos.transform`. If you rename or remove tree nodes, values or conditions, add the corresponding rule to `kratos.transform`. Otherwise existing user models lose data.

The minimum GiD version is `MinimumGiDVersion` in `kratos.xml`. Some `app.json` files declare older values; the global one is the effective minimum.

## Testing

- No unit tests in this repo. Integration tests live in [kratos-gid-tester](https://github.com/jginternational/kratos-gid-tester): it runs GiD batch files (`batchs/<App>/*.bch`) that build each example, write the Kratos input and, for `*_calculate` cases, run the simulation.
- CI: `.github/workflows/tester.yml`, image `fjgarate/kratos-tester`, self-hosted runner. It runs on push to `master` and on PRs labelled `safe-to-test`.
- Manual check: link `kratos.gid` into GiD's `problemtypes`, load the problemtype, open the relevant example, *Calculate*, and inspect the generated files in the model folder.
- Without GiD you can only review syntax and logic. Say so when reporting results instead of claiming the change was tested.

## Rules

- Do not edit `dist/`, `libs/`, or generated/ignored files (`exec/Kratos*`, `__pycache__`).
- `*.unix.bat` and `*.sh` must keep **LF** line endings; `*.win.bat` CRLF.
- Keep XML files UTF-8 and preserve each file's existing indentation (some use tabs, others spaces).
- Do not rename tree nodes, `n=` attributes or unique names without a `kratos.transform` rule.
- Use `Kratos::Log` for debug output rather than `W` in committed code.
- Release scripts (`tools/create-release.bat`) create and force-push tags: do not run them unless asked.
149 changes: 97 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,106 @@
# KratosMultiphysics <-> GiD Interface

[![Codacy Badge](https://app.codacy.com/project/badge/Grade/36d3d305c87e4bb398bc87ea2e3b890e)](https://www.codacy.com/gh/KratosMultiphysics/GiDInterface/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=KratosMultiphysics/GiDInterface&amp;utm_campaign=Badge_Grade)
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/36d3d305c87e4bb398bc87ea2e3b890e)](https://app.codacy.com/gh/KratosMultiphysics/GiDInterface/dashboard)
[![Tester](https://github.com/KratosMultiphysics/GiDInterface/actions/workflows/tester.yml/badge.svg)](https://github.com/KratosMultiphysics/GiDInterface/actions/workflows/tester.yml)

The user interface of Kratos with [GiD](http://www.gidsimulation.com).

If you need the latest stable release, launch your GiD, navigate to Data > Problemtype > Internet retrieve and download Kratos there.
Available for Linux. Windows, and macOS.

If you need the developer version, you are on the right place.

## First steps
* 1- Clone this repository, or install a stable [release](https://github.com/KratosMultiphysics/GiDInterface/releases)
* 2- Install the latest GiD developer version **(minimum 16.1.4d)** -> [Developer version](https://www.gidsimulation.com/gid-for-science/downloads/)
* 3- Navigate to GiD's problemtype folder and delete any previous kratos.gid
* Create there a link to our [kratos.gid](./kratos.gid/) downloaded in step 1
* Windows: Simple shortcut to kratos.gid folder
* 4- Choose your execution mode:
* 4.1- **Default execution mode.** Use GiD's python:
* You don't need to install python. The program will detect if you have any pending package to install.
* If there's any missing package, use the GiD command line and execute:

`-np- W [GiD_Python_PipInstall { $::Kratos::pip_packages_required } 1 ]`
* 4.1- To execute Kratos using the standard pip packages:
* Python version recommended: 3.8, 3.9, 3.10, 3.11, 3.12
* Open a terminal and run
- Linux: `python3 -m pip install --upgrade --force-reinstall --no-cache-dir KratosMultiphysics[all]==10.4.3`
- Windows: `python -m pip install --upgrade --force-reinstall --no-cache-dir KratosMultiphysics[all]==10.4.3`
* 4.2- To execute Kratos using your compiled binaries:
* Fill the Kratos preferences windows with
- Path to the python folder
- Path to the kratos build folder
* Step by step video: https://www.youtube.com/watch?v=zZq7ypDdudo
* 4.3- To execute Kratos using docker, just install docker.
* Note: This is the ONLY option if you are a **macOS** user at this moment

### Launch modes
In Kratos preferences, select the execution mode:
* GiD's python: Use the GiD internal python to run. It will help you install the pip packages
* Pip packages: Kratos will be installed via `pip install`
* local compiled: If you are a developer and build your applications, use this one
* docker: If you do not want to install any dependency, just run via docker!
* The default image is [fjgarate/kratos-run](https://hub.docker.com/repository/docker/fjgarate/kratos-run)

### Usage
* Run GiD
* Go to top menu: Data / Problem type / kratos
* Go to top menu: kratos / Preferences / Developer mode (recommended)
The graphical user interface of [Kratos Multiphysics](https://github.com/KratosMultiphysics/Kratos) for [GiD](https://www.gidsimulation.com), distributed as a GiD *problemtype* (`kratos.gid`).

- **Stable release:** open GiD, go to *Data > Problem type > Internet retrieve* and download Kratos. Available for Linux, Windows and macOS.
- **Developer version:** you are in the right place.

Current version: **Kratos 10.4.3** — requires **GiD 16.1.10d or newer** (developer version recommended).

## Installation (developer version)

1. Clone this repository, or download a [release](https://github.com/KratosMultiphysics/GiDInterface/releases).
2. Install the latest [GiD developer version](https://www.gidsimulation.com/gid-for-science/downloads/) (minimum **16.1.10d**).
3. Go to GiD's `problemtypes` folder and delete any previous `kratos.gid`.
4. Create there a link to the [`kratos.gid`](./kratos.gid/) folder of this repository:
- Windows: a shortcut to the `kratos.gid` folder.
- Linux / macOS: `ln -s /path/to/GiDInterface/kratos.gid /path/to/GiD/problemtypes/kratos.gid`
5. Choose an execution mode (see below).

## Execution modes

Select the mode in *Kratos > Preferences*.

| Mode | What you need | Notes |
|---|---|---|
| **GiD's python** (default) | Nothing | Uses the Python bundled with GiD. Missing packages are detected and can be installed from the interface. |
| **Pip packages** | Python + `KratosMultiphysics[all]` | Use a Python version supported by the [KratosMultiphysics 10.4.3 wheels](https://pypi.org/project/KratosMultiphysics/10.4.3/#files). |
| **Local compiled** | Your own Kratos build | For Kratos developers. |
| **Docker** | Docker | No other dependency. Currently the **only option on macOS**. Default image: [`fjgarate/kratos-run`](https://hub.docker.com/r/fjgarate/kratos-run). |

### GiD's python
If some package is missing, run this in the GiD command line:

```
-np- W [GiD_Python_PipInstall { $::Kratos::pip_packages_required } 1 ]
```

### Pip packages
```bash
# Linux
python3 -m pip install --upgrade --force-reinstall --no-cache-dir KratosMultiphysics[all]==10.4.3
# Windows
python -m pip install --upgrade --force-reinstall --no-cache-dir KratosMultiphysics[all]==10.4.3
```

### Local compiled
In *Kratos > Preferences* fill in:
- the path to the Python folder
- the path to the Kratos build folder

Step-by-step video: https://www.youtube.com/watch?v=zZq7ypDdudo

## Usage
1. Run GiD.
2. *Data > Problem type > kratos*.
3. *Kratos > Preferences > Developer mode* (recommended for developers).
4. Pick an application in the application market window.

### Examples
* [Fluid dynamics example](https://github.com/KratosMultiphysics/Kratos/wiki/Running-an-example-from-GiD#3-set-a-fluid-dynamics-problem)
* [Structural mechanics example](https://github.com/KratosMultiphysics/Kratos/wiki/Running-an-example-from-GiD#4-set-a-structural-mechanics-problem)
* [Fluid-Structure interaction example](https://github.com/KratosMultiphysics/Kratos/wiki/Running-an-example-from-GiD#5-set-a-fluid-structure-interaction-problem)
- [Fluid dynamics](https://github.com/KratosMultiphysics/Kratos/wiki/Running-an-example-from-GiD#3-set-a-fluid-dynamics-problem)
- [Structural mechanics](https://github.com/KratosMultiphysics/Kratos/wiki/Running-an-example-from-GiD#4-set-a-structural-mechanics-problem)
- [Fluid-structure interaction](https://github.com/KratosMultiphysics/Kratos/wiki/Running-an-example-from-GiD#5-set-a-fluid-structure-interaction-problem)

Many applications also ship ready-to-run examples (*Examples* tool inside the interface).

## Applications

Public applications (shown in the application market): Structural, Fluid, FSI, Dam, Thermic, Pfem, DEM, MPM, Shallow water, GeoMechanics, and the tools Stenosis Wizard, Stent, Mdpa Generator and Examples.

Others (CompressibleFluid, EmbeddedFluid, Buoyancy, ConjugateHeatTransfer, PfemFluid, CDEM, …) are reachable through the launchers or in developer mode. The full list lives in the `appLink` entries of [`kratos.gid/kratos.spd`](./kratos.gid/kratos.spd).

## Repository layout

```
kratos.gid/ The GiD problemtype
kratos.tcl Entry point (GiD events, init, version checks)
kratos.xml Problemtype metadata (version, min GiD version, pip packages)
kratos.spd Root of the data tree; lists the applications (appLink)
kratos.transform Rules to upgrade models saved with older versions
apps/<App>/ One folder per application: app.json, start.tcl, xml/, write/, examples/
apps/Common/ Shared XML/SPD definitions
scripts/ Core: Model/ (entities), Writing/ (mdpa + json), Controllers/ (windows)
exec/ Launch scripts per mode and OS, MainKratos.py
libs/ Third-party Tcl libraries
tools/ Release scripts
dockers/ Release / runner docker images
```

## Testing

CI runs the [kratos-gid-tester](https://github.com/jginternational/kratos-gid-tester) suite in the `fjgarate/kratos-tester` image on a self-hosted runner, on every push to `master`. Pull requests are tested only after a maintainer adds the `safe-to-test` label.

## Contributing

1. Fork the repository and create a branch from `master`.
2. Make your changes and test them in GiD (see [AGENTS.md](./AGENTS.md) for the code structure and conventions).
3. Open a pull request against `master`.

## Warnings
* This repository is in Beta version. This means that everything can change.
Questions: open an [issue](https://github.com/KratosMultiphysics/GiDInterface/issues).

## Want to develop?
* Ask for access -> contact fjgarate@cimne.upc.edu
## License

See [LICENSE.md](./LICENSE.md).
Loading
Loading