From 969f194f9a4b51af101bc7fc5c1bbf0007b91aee Mon Sep 17 00:00:00 2001 From: Olivier Hoenen Date: Wed, 25 Mar 2026 15:31:35 +0100 Subject: [PATCH 1/3] some fixes and updates in user/tuto documentation --- docs/tutorial.md | 50 +++++++++++++++++++++++++++++++++++----------- docs/user_guide.md | 7 ++++--- 2 files changed, 42 insertions(+), 15 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 6952ac6..a7c608b 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -14,7 +14,7 @@ simdb --version This should return something similar to: ``` -simdb, version 0.4.0 +simdb, version x.y.z ``` This indicates the CLI is available and shows what version has been installed. @@ -123,16 +123,14 @@ metadata: - description: |- Baseline H-mode scenario simulation for ITER 15MA plasma current with Q=10 target - - reference_name: ITER_Baseline_2024 - ids_properties: - creation_date: '2024-12-05 10:30:00' + creation_date: "2024-12-05 10:30:00" ``` Metadata Best Practices: - **machine**: Always specify the tokamak or device name - **code**: Include both name and version for reproducibility - **description**: Provide context about the simulation purpose and key features -- **reference_name**: Use a human-readable reference identifier - **ids_properties**: Include creation date if not available in IDS data ### Validating a Manifest File @@ -167,10 +165,10 @@ simdb simulation list And the simulation you have just ingested with: ```bash -simdb simulation info test +simdb simulation info ``` -## Pushing the simulation to remote server +## Pushing the simulation to a remote server The SimDB client is able to communication with multiple remote servers. You can see which remote servers are available on your local client using: @@ -179,21 +177,49 @@ on your local client using: simdb remote config list ``` -First, you will need to add the remote server and set it as default: +First, you will need to add the remote server and set it as default (name and url may differ): ```bash -simdb remote --new test https://simdb.iter.org/scenarios/api -simdb remote --set-default test +simdb remote --new iter https://simdb.iter.org/scenarios/api +simdb remote --set-default iter ``` -You can now list the simulations available on the remote server: +You can test that the remote server is valid and also list the simulations available on it: ```bash -simdb remote list +simdb remote test +simdb remote list ``` +You can now check that your simulation is valid for a given remote server, as different servers may have different +rules and required fields: + +```bash +simdb simulation validate +``` + +Typical validation issues are: +- one of the data sources (input or output) being absent or not verifying the checksum (i.e. something changed since the ingestion); +- failing to comply with the list of mandatory metadata for the targeted remote. + +It it possible to know which validation schema applies on a given remote: + +```bash +simdb remote schema -d 10 +``` + +If the `validate` command results in a `validation successful` message, then you can push your simulation: + +```bash +simdb simulation push +``` + + +## Authentication + Whenever you run a remote command you will notice that you have to authenticate against the remote server. This can be -avoided by creating an authentication token using: +avoided by creating an authentication token using for servers that allows such method (not applicable to simdb.iter.org +which uses F5 firewall as authentication layer): ```bash simdb remote token new diff --git a/docs/user_guide.md b/docs/user_guide.md index 9f6f7f0..cc6421a 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -60,14 +60,15 @@ inputs: - uri: file:///my/input/file - uri: imas:hdf5?path=/path/to/imas/data outputs: +- uri: file:///my/output/file - uri: imas:hdf5?path=/path/to/more/data metadata: - machine: name of machine i.e. ITER. - code: - name: code name i.e. ASTRA, JETTO, DINA, CORSICA, MITES, SOLPS, JINTRAC etc. -- description: |- + name: code name i.e. ASTRA, JETTO, DINA, CORSICA, METIS, SOLPS, JINTRAC etc. + version: code version +- description: | Sample plasma physics simulation for ITER tokamak modeling -- reference_name: ITER simulation - ids_properties: creation_date: 'YYYY-MM-DD HH:mm:ss' ``` From 9db9c6ab30fc6d390055045ad2c255f8522b6900 Mon Sep 17 00:00:00 2001 From: Olivier Hoenen Date: Wed, 25 Mar 2026 15:54:53 +0100 Subject: [PATCH 2/3] Update docs/tutorial.md Co-authored-by: Simon Pinches --- docs/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index a7c608b..1c320af 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -218,7 +218,7 @@ simdb simulation push ## Authentication Whenever you run a remote command you will notice that you have to authenticate against the remote server. This can be -avoided by creating an authentication token using for servers that allows such method (not applicable to simdb.iter.org +avoided by creating an authentication token for servers that allow such a method (not applicable for simdb.iter.org which uses F5 firewall as authentication layer): ```bash From a6e0eacfa049dbe2234b63cf4c926f7e6e591ce6 Mon Sep 17 00:00:00 2001 From: Olivier Hoenen Date: Thu, 26 Mar 2026 17:36:06 +0100 Subject: [PATCH 3/3] Add description of push --replaces and trace in the tutorial --- docs/tutorial.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/tutorial.md b/docs/tutorial.md index 1c320af..5de45e8 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -214,6 +214,19 @@ If the `validate` command results in a `validation successful` message, then you simdb simulation push ``` +If the simulation is expected to replace another one already present in the remote server: + +```bash +simdb simulation push --replaces +``` + +The previous simulation will be marked as deprecated and contain a new `replaced_by` metadata that points to +``. It's also possible to see the chained history of older versions if they exist: + +```bash +simdb remote trace +``` + ## Authentication