Repository: FAIRmat-NFDI/fairmat-tutorial-DPG-2025
Pull request #17: fixes
Author: login: andreaa93
Created: 2025-03-12T09:05:39Z | Merged: 2025-03-13T15:43:08Z

The last checks before removing the preliminary draft banners


Diff:
diff --git a/data/Custom_ELN_Entries.zip b/data/Custom_ELN_Entries.zip
index 640a01f..865c7e4 100644
Binary files a/data/Custom_ELN_Entries.zip and b/data/Custom_ELN_Entries.zip differ
diff --git a/docs/api.md b/docs/api.md
index 9513f9f..169c948 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -14,8 +14,8 @@
 
 *Your Approach:* Use the NOMAD workflow utility plugin!
 
-!!! NOTE
-    When using the NOMAD workflow utility plugin, be sure to execute all the commands in a jupyter notebook or in the same python session.
+!!! Warning "Attention"
+    The exercises have to be performed in a jupyter notebook (several will be provided during the tutorial) or in the same terminal/python session to retain the imported packages and defined variables during each step.
 
 ## Set up / files and data
 
diff --git a/docs/assets/Custom_ELN_Entries.zip b/docs/assets/Custom_ELN_Entries.zip
new file mode 100644
index 0000000..47ac110
Binary files /dev/null and b/docs/assets/Custom_ELN_Entries.zip differ
diff --git a/docs/assets/simulation-setup-files.zip b/docs/assets/simulation-setup-files.zip
index fa0cd62..52c6431 100644
Binary files a/docs/assets/simulation-setup-files.zip and b/docs/assets/simulation-setup-files.zip differ
diff --git a/docs/assets/simulation-setup-yamls.zip b/docs/assets/simulation-setup-yamls.zip
deleted file mode 100644
index d83f4ae..0000000
Binary files a/docs/assets/simulation-setup-yamls.zip and /dev/null differ
diff --git a/docs/core.md b/docs/core.md
index 6bccd6b..41e2841 100644
--- a/docs/core.md
+++ b/docs/core.md
@@ -99,7 +99,6 @@ Now go to the [Test NOMAD Deployment](https://nomad-lab.eu/prod/v1/test/gui/sear
 <video width="100%" controls>
   <source src="../assets/drag-and-drop.webm" alt="File Upload" width="100%" type="video/mp4">
 </video>
-<!-- <button onclick="document.getElementById('drag_and_drop').pause();">Pause</button> -->
 
 ## Browse the entry pages
 
diff --git a/docs/custom.md b/docs/custom.md
index 822125c..b26ad33 100644
--- a/docs/custom.md
+++ b/docs/custom.md
@@ -15,8 +15,7 @@ _Challenge:_ You need to include the simulation setup procedure with sufficient
 _Your Approach:_ Use the NOMAD electronic lab notebook (ELN) and custom schema functionalities!
 
 !!! Warning "Attention"
-
-    The exercises have to be performed in the same `terminal`/`python session`, or the non-permanent addition of the tutorial directory to your `$PYTHONPATH` will be reset.
+    The exercises have to be performed in a jupyter notebook (provided below) or in the same terminal/python session to retain the imported packages and defined variables during each step.
 
 ## Simulation setup steps
 
@@ -78,7 +77,7 @@ Uploading this yaml to the test deployment results in an entry with the overview
     </label>
 </div>
 
-If you want to use the API for your upload, check out [Part 2](api.md#uploading-api-basics)
+If you want to use the API for your upload, check out the box ["API calls from the terminal"](api.md#uploading-api-basics) in Part 2.
 
 ## Customizing the schema
 
@@ -125,13 +124,16 @@ The section `AnnotationFile` contains 2 quantities `file` and `description` for
 
 ??? tip "More on custom schemas"
 
-    The YAML approach is a quick and dirty way to customize your NOMAD entries. It doesn't allow for complete integration of custom defined quantities within the database bacause the schema is injested via YAML file while NOMAD platform is running, in contrast to the quantities belonging to schemas organized in **plugins** (python packages) and installed in NOMAD during deployment. See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
+    The YAML approach is a quick and dirty way to customize your NOMAD entries. 
+    To disincentivise the proliferation of _ad-hoc_ schemas and remain FAIR, YAML sections or quantities only have partial support. 
+    Seamless integration of new quantities happens when schemas are organized in **plugins** (python packages) and installed in NOMAD during deployment. 
+    See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
 
     The more robust and powerful approach for creating custom schemas is to create a *schema plugin* (see [NOMAD Docs > How to get started with plugins](https://nomad-lab.eu/prod/v1/test/docs/howto/plugins/plugins.html){:target="_blank"}).
 
     Useful resources for plugin developers are the [Plugin Template](https://github.com/FAIRmat-NFDI/nomad-plugin-template) and the [NOMAD Distro Template](https://github.com/FAIRmat-NFDI/nomad-distro-template).
 
-We can now use these defintions to create an entry file for the step of creating the force field file (as illustrated in the image above):
+We can now use these definitions to create an entry file for the step of creating the force field file (as illustrated in the image above):
 
 <h4><code>create_force_field.archive.yaml</code></h4>
 ```yaml
@@ -151,65 +153,53 @@ You can now create analogous files `create_box.archive.yaml`, `insert_water.arch
 ??? success "`create_box.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Create box'
-          description: 'The initial simulation box is created.'
-          Files:
-          - file: 'Custom_ELN_Entries/box.gro'
-              description: 'An empty structure file with the box vectors.'
-    ```
-
-??? success "`insert_water.archive.yaml`"
-
-    ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Create box'
+      description: 'The initial simulation box is created.'
+      Files:
+      - file: 'Custom_ELN_Entries/box.gro'
+        description: 'An empty structure file with the box vectors.'
     ```
 
 ??? success "`insert_water.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Insert water'
+      description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
+      Files:
+      - file: 'Custom_ELN_Entries/water.gro'
+        description: 'The structure file for simulation input.'
     ```
 
 ??? success "`workflow_parameters.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
-          name: 'Workflow Parameters'
-          description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
+    data:
+      m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
+      name: 'Workflow Parameters'
+      description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
     ```
 
 ??? success "`workflow_scripts.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Workflow Scripts'
-          description: 'All the scripts run during setup of the MD simulation.'
-          Files:
-          - file: 'Custom_ELN_Entries/workflow_script_1.py'
-              description: 'Creates the simulation box and inserts water molecules.'
-          - file: 'Custom_ELN_Entries/workflow_script_2.py'
-              description: 'Creates the appropriate force field files for the simulation engine.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Workflow Scripts'
+      description: 'All the scripts run during setup of the MD simulation.'
+      Files:
+      - file: 'Custom_ELN_Entries/workflow_script_1.py'
+        description: 'Creates the simulation box and inserts water molecules.'
+      - file: 'Custom_ELN_Entries/workflow_script_2.py'
+        description: 'Creates the appropriate force field files for the simulation engine.'
     ```
 
 ## Creating a custom workflow in NOMAD
 
-NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow.
+NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow. Learn more about the [archive file structure](https://nomad-lab.eu/prod/v1/test/docs/explanation/data.html#archive-files-a-shared-entry-structure) in the official NOMAD documentation.
 
 Let's construct this workflow yaml piece by piece, starting with the section definition and global inputs/outputs:
 
@@ -258,7 +248,7 @@ You can now add the "create box" and "insert water" tasks to create the final wo
 
 ??? success "`setup_workflow.archive.yaml`"
 
-```yaml
+    ```yaml
     "workflow2":
       "name": "MD Setup workflow"
       "inputs":
@@ -305,12 +295,12 @@ You can now add the "create box" and "insert water" tasks to create the final wo
           "outputs":
           - "name": "force field file"
           "section": "<path_to_mainfile>/create_force_field.archive.yaml#/data/Files/0/file"
-```
+    ```
 
 Place all of the completed files into a folder called `Custom_ELN_Entries/`. Don't forget to replace `<path_to_mainfile>` with `../upload/archive/mainfile/Custom_ELN_Entries/`. Alternatively, you can download the completed yamls here:
 
 <center>
-[Download Simulation Setup YAMLs](assets/simulation-setup-yamls.zip){:target="_blank" .md-button}
+[Download Custom_ELN_Entries folder](assets/Custom_ELN_Entries.zip){:target="_blank" .md-button}
 </center>
 
 ## Uploading and publishing
@@ -430,7 +420,7 @@ Create a new notebook `Custom_ELN_Entries.ipynb` to try the steps below on your
 
 ## Saving the PIDs
 
-For Part 4, we will need the entry ids for the setup workflow entry and the workflow parameters entry (input for the md setup workflow). Find the proper entry ids using the GUI or the `get_entries_of_upload()` method as in Part 2. Copy the `entry_id` for each into your `PIDs.json` file:
+For Part 4, we will need the entry ids for the setup workflow entry (`setup_workflow.archive.yaml`) and the workflow parameters entry (`workflow_parameters.archive.yaml`), that is the input for the md setup workflow. Find the proper entry ids using the GUI or the `get_entries_of_upload()` method as in Part 2. Copy the `entry_id` for each into your `PIDs.json` file:
 
 ```json
 {
@@ -440,7 +430,7 @@ For Part 4, we will need the entry ids for the setup workflow entry and the work
   "entry_ids": {
     "md-workflow": "<your md workflow entry id from Part 1>",
     "DFT": ["<your list of dft entry ids from above>"],
-    "setup-workflow": "",
+    "setup-workflow": "<copy the setup workflow entry id here>",
     "parameters": "<copy the workflow parameters entry id here>",
     "analysis": ""
   },
diff --git a/docs/workflows.md b/docs/workflows.md
index 300f6dc..021aed7 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -30,9 +30,9 @@ _Your Approach:_
 
 You have performed some vibrational analysis of the DFT configurations obtained from your simulations. The results are shown below. Create a file `result-vibrational-analysis-DFT.csv` to store the results:
 
-```
+```txt
 electron_density,oh_stretch_frequency
-au,1/cm
+e/A^3,1/cm
 0.0102,3601.
 0.0125,3554.
 0.0140,3507.
@@ -129,8 +129,8 @@ After you have completed the publishing, save the `entry_id` to your `PIDs.json`
   "entry_ids": {
     "md-workflow": "<your md workflow entry id from Part 1>",
     "DFT": ["<your list of dft entry ids from above>"],
-    "setup-workflow": "",
-    "parameters": "<your workflow parameters entry id here>",
+    "setup-workflow": "<your setup workflow entry id from Part 3>",
+    "parameters": "<your workflow parameters entry id from Part 3>",
     "analysis": "<copy the vibrational analysis entry id here>"
   },
   "dataset_id": "<your dataset id>"
@@ -310,68 +310,68 @@ gv.d3(
 
 We see that our output graph looks signficantly different than the input. That's because `nomad-utility-workflow` is automatically adding some default inputs/outputs to ensure the proper node connections within the workflow visualizer. For nodes without an `entry_type`, these default connections work by simply adding inputs/outputs that point to the mainfile of one of the nodes connected by an edge in the graph.
 
-Open the generated `project_workflow.archive.yaml`:
+??? success "example `project_workflow.archive.yaml`"
 
-```yaml
-"workflow2":
-  "name": "DPG Tutorial 2025 Project Workflow"
-  "inputs":
-    - "name": "Workflow Parameters"
-      "section": "/entries/Lyku0eClZtAGwwY9o7vWeKL-7YWK/archive/mainfile/workflow_parameters.archive.yaml#/data"
-  "outputs":
-    - "name": "Vibrational Analysis"
-      "section": "/entries/G74EVJ4bCbjLlFKs-Oytxqzv7E0H/archive/mainfile/vibrational_analysis.archive.yaml#/data"
-  "tasks":
-    - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
-      "name": "MD Setup"
-      "task": "/entries/Gqm3Tek---QCH2z0FwTqkEhtvV1s/archive/mainfile/setup_workflow.archive.yaml#/workflow2"
+    ```yaml
+    "workflow2":
+      "name": "DPG Tutorial 2025 Project Workflow"
       "inputs":
-        - "name": "Link to global input"
+        - "name": "Workflow Parameters"
           "section": "/entries/Lyku0eClZtAGwwY9o7vWeKL-7YWK/archive/mainfile/workflow_parameters.archive.yaml#/data"
       "outputs":
-        - "name": "workflow2 section of node 2"
-          "section": "/entries/ERvFmh9BlclnU-Ai3ohQP-6vZJjf/archive/mainfile/workflow.archive.yaml#/workflow2"
-    - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
-      "name": "MD Equilibration"
-      "task": "/entries/ERvFmh9BlclnU-Ai3ohQP-6vZJjf/archive/mainfile/workflow.archive.yaml#/workflow2"
-      "inputs":
-        - "name": "workflow2 section of node 2"
-          "section": "/entries/ERvFmh9BlclnU-Ai3ohQP-6vZJjf/archive/mainfile/workflow.archive.yaml#/workflow2"
-      "outputs":
-        - "name": "workflow2 section of node 3"
-          "section": "/entries/iJi7Q-C97J2BEupZVEgGq-TEZf5N/archive/mainfile/aims.out#/workflow2"
-        - "name": "workflow2 section of node 4"
-          "section": "/entries/7B0NdXAK7wqjHNX2yPR3ghdwdjG2/archive/mainfile/aims.out#/workflow2"
-        - "name": "workflow2 section of node 5"
-          "section": "/entries/15UO3IElPxAFZG3xl0tmmyhyLoHa/archive/mainfile/aims.out#/workflow2"
-    - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
-      "name": "DFT-1"
-      "task": "/entries/iJi7Q-C97J2BEupZVEgGq-TEZf5N/archive/mainfile/aims.out#/workflow2"
-      "inputs":
-        - "name": "workflow2 section of node 3"
-          "section": "/entries/iJi7Q-C97J2BEupZVEgGq-TEZf5N/archive/mainfile/aims.out#/workflow2"
-      "outputs":
-        - "name": "Link to global output"
+        - "name": "Vibrational Analysis"
           "section": "/entries/G74EVJ4bCbjLlFKs-Oytxqzv7E0H/archive/mainfile/vibrational_analysis.archive.yaml#/data"
-    - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
-      "name": "DFT-2"
-      "task": "/entries/7B0NdXAK7wqjHNX2yPR3ghdwdjG2/archive/mainfile/aims.out#/workflow2"
-      "inputs":
-        - "name": "workflow2 section of node 4"
-          "section": "/entries/7B0NdXAK7wqjHNX2yPR3ghdwdjG2/archive/mainfile/aims.out#/workflow2"
-      "outputs":
-        - "name": "Link to global output"
-          "section": "/entries/G74EVJ4bCbjLlFKs-Oytxqzv7E0H/archive/mainfile/vibrational_analysis.archive.yaml#/data"
-    - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
-      "name": "DFT-3"
-      "task": "/entries/15UO3IElPxAFZG3xl0tmmyhyLoHa/archive/mainfile/aims.out#/workflow2"
-      "inputs":
-        - "name": "workflow2 section of node 5"
-          "section": "/entries/15UO3IElPxAFZG3xl0tmmyhyLoHa/archive/mainfile/aims.out#/workflow2"
-      "outputs":
-        - "name": "Link to global output"
-          "section": "/entries/G74EVJ4bCbjLlFKs-Oytxqzv7E0H/archive/mainfile/vibrational_analysis.archive.yaml#/data"
-```
+      "tasks":
+        - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
+          "name": "MD Setup"
+          "task": "/entries/Gqm3Tek---QCH2z0FwTqkEhtvV1s/archive/mainfile/setup_workflow.archive.yaml#/workflow2"
+          "inputs":
+            - "name": "Link to global input"
+              "section": "/entries/Lyku0eClZtAGwwY9o7vWeKL-7YWK/archive/mainfile/workflow_parameters.archive.yaml#/data"
+          "outputs":
+            - "name": "workflow2 section of node 2"
+              "section": "/entries/ERvFmh9BlclnU-Ai3ohQP-6vZJjf/archive/mainfile/workflow.archive.yaml#/workflow2"
+        - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
+          "name": "MD Equilibration"
+          "task": "/entries/ERvFmh9BlclnU-Ai3ohQP-6vZJjf/archive/mainfile/workflow.archive.yaml#/workflow2"
+          "inputs":
+            - "name": "workflow2 section of node 2"
+              "section": "/entries/ERvFmh9BlclnU-Ai3ohQP-6vZJjf/archive/mainfile/workflow.archive.yaml#/workflow2"
+          "outputs":
+            - "name": "workflow2 section of node 3"
+              "section": "/entries/iJi7Q-C97J2BEupZVEgGq-TEZf5N/archive/mainfile/aims.out#/workflow2"
+            - "name": "workflow2 section of node 4"
+              "section": "/entries/7B0NdXAK7wqjHNX2yPR3ghdwdjG2/archive/mainfile/aims.out#/workflow2"
+            - "name": "workflow2 section of node 5"
+              "section": "/entries/15UO3IElPxAFZG3xl0tmmyhyLoHa/archive/mainfile/aims.out#/workflow2"
+        - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
+          "name": "DFT-1"
+          "task": "/entries/iJi7Q-C97J2BEupZVEgGq-TEZf5N/archive/mainfile/aims.out#/workflow2"
+          "inputs":
+            - "name": "workflow2 section of node 3"
+              "section": "/entries/iJi7Q-C97J2BEupZVEgGq-TEZf5N/archive/mainfile/aims.out#/workflow2"
+          "outputs":
+            - "name": "Link to global output"
+              "section": "/entries/G74EVJ4bCbjLlFKs-Oytxqzv7E0H/archive/mainfile/vibrational_analysis.archive.yaml#/data"
+        - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
+          "name": "DFT-2"
+          "task": "/entries/7B0NdXAK7wqjHNX2yPR3ghdwdjG2/archive/mainfile/aims.out#/workflow2"
+          "inputs":
+            - "name": "workflow2 section of node 4"
+              "section": "/entries/7B0NdXAK7wqjHNX2yPR3ghdwdjG2/archive/mainfile/aims.out#/workflow2"
+          "outputs":
+            - "name": "Link to global output"
+              "section": "/entries/G74EVJ4bCbjLlFKs-Oytxqzv7E0H/archive/mainfile/vibrational_analysis.archive.yaml#/data"
+        - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
+          "name": "DFT-3"
+          "task": "/entries/15UO3IElPxAFZG3xl0tmmyhyLoHa/archive/mainfile/aims.out#/workflow2"
+          "inputs":
+            - "name": "workflow2 section of node 5"
+              "section": "/entries/15UO3IElPxAFZG3xl0tmmyhyLoHa/archive/mainfile/aims.out#/workflow2"
+          "outputs":
+            - "name": "Link to global output"
+              "section": "/entries/G74EVJ4bCbjLlFKs-Oytxqzv7E0H/archive/mainfile/vibrational_analysis.archive.yaml#/data"
+    ```
 
 Now upload, edit the metadata, and publish `project_workflow.archive.yaml` following [Part 3 > Uploading and Publishing](./custom.md#uploading-and-publishing). Browse the workflow graph of this entry to see how it links all of your uploads together.
 


Reviews:
user: login: ndaelman-hu
body: Thx for the corrections. Like the indentations and admonitions.
Just some comments on the wording.
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:11:28Z
user: login: andreaa93
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:17:35Z
user: login: andreaa93
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:21:42Z
user: login: andreaa93
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:22:41Z
user: login: andreaa93
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:24:34Z
user: login: andreaa93
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:26:01Z
user: login: andreaa93
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:26:46Z
user: login: ndaelman-hu
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-03-13T15:38:41Z

Review comments:
diff_hunk: @@ -14,8 +14,8 @@
 
 *Your Approach:* Use the NOMAD workflow utility plugin!
 
-!!! NOTE
-    When using the NOMAD workflow utility plugin, be sure to execute all the commands in a jupyter notebook or in the same python session.
+!!! Warning "Attention"
+    The exercises have to be performed in a jupyter notebook (provided below) or in the same terminal/python session to retain the imported packages and defined variables during each step. 
path: docs/api.md
user: login: ndaelman-hu
body: I like the admonition, but users will encounter multiple notebooks.
Maybe add: "... per Part."?
created_at: 2025-03-13T14:50:56Z
author_association: COLLABORATOR
diff_hunk: @@ -125,13 +124,13 @@ The section `AnnotationFile` contains 2 quantities `file` and `description` for
 
 ??? tip "More on custom schemas"
 
-    The YAML approach is a quick and dirty way to customize your NOMAD entries. It doesn't allow for complete integration of custom defined quantities within the database bacause the schema is injested via YAML file while NOMAD platform is running, in contrast to the quantities belonging to schemas organized in **plugins** (python packages) and installed in NOMAD during deployment. See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
+    The YAML approach is a quick and dirty way to customize your NOMAD entries. It doesn't allow for complete integration of custom defined quantities within the database search tools to avoid uncontrolled proliferation of schemas that would be detrimental for data FAIRness. Seamless integration of new quantities happens when schemas are organized in **plugins** (python packages) and installed in NOMAD during deployment. See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
path: docs/custom.md
user: login: ndaelman-hu
body: The phrase is still quite hard to read, in both versions. Had to read it twice... Suggested change:

"To disincentivise the proliferation of ad-hoc schemas and remain FAIR, Yaml sections or quantities only have partial support."

Btw, I think there are also real technical stumbling blocks, but this is a nice spin.
created_at: 2025-03-13T14:56:26Z
author_association: COLLABORATOR
diff_hunk: @@ -125,13 +124,13 @@ The section `AnnotationFile` contains 2 quantities `file` and `description` for
 
 ??? tip "More on custom schemas"
 
-    The YAML approach is a quick and dirty way to customize your NOMAD entries. It doesn't allow for complete integration of custom defined quantities within the database bacause the schema is injested via YAML file while NOMAD platform is running, in contrast to the quantities belonging to schemas organized in **plugins** (python packages) and installed in NOMAD during deployment. See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
+    The YAML approach is a quick and dirty way to customize your NOMAD entries. It doesn't allow for complete integration of custom defined quantities within the database search tools to avoid uncontrolled proliferation of schemas that would be detrimental for data FAIRness. Seamless integration of new quantities happens when schemas are organized in **plugins** (python packages) and installed in NOMAD during deployment. See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
path: docs/custom.md
user: login: ndaelman-hu
body: Protip: I always split my sentences in (mkdocs) markdown. It doesn't affect the rendering, but makes git changes more precise.
created_at: 2025-03-13T14:58:45Z
author_association: COLLABORATOR
diff_hunk: @@ -151,65 +150,53 @@ You can now create analogous files `create_box.archive.yaml`, `insert_water.arch
 ??? success "`create_box.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Create box'
-          description: 'The initial simulation box is created.'
-          Files:
-          - file: 'Custom_ELN_Entries/box.gro'
-              description: 'An empty structure file with the box vectors.'
-    ```
-
-??? success "`insert_water.archive.yaml`"
-
-    ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Create box'
+      description: 'The initial simulation box is created.'
+      Files:
+      - file: 'Custom_ELN_Entries/box.gro'
+        description: 'An empty structure file with the box vectors.'
     ```
 
 ??? success "`insert_water.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Insert water'
+      description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
+      Files:
+      - file: 'Custom_ELN_Entries/water.gro'
+        description: 'The structure file for simulation input.'
     ```
 
 ??? success "`workflow_parameters.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
-          name: 'Workflow Parameters'
-          description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
+    data:
+      m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
+      name: 'Workflow Parameters'
+      description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
     ```
 
 ??? success "`workflow_scripts.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Workflow Scripts'
-          description: 'All the scripts run during setup of the MD simulation.'
-          Files:
-          - file: 'Custom_ELN_Entries/workflow_script_1.py'
-              description: 'Creates the simulation box and inserts water molecules.'
-          - file: 'Custom_ELN_Entries/workflow_script_2.py'
-              description: 'Creates the appropriate force field files for the simulation engine.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Workflow Scripts'
+      description: 'All the scripts run during setup of the MD simulation.'
+      Files:
+      - file: 'Custom_ELN_Entries/workflow_script_1.py'
+        description: 'Creates the simulation box and inserts water molecules.'
+      - file: 'Custom_ELN_Entries/workflow_script_2.py'
+        description: 'Creates the appropriate force field files for the simulation engine.'
     ```
 
 ## Creating a custom workflow in NOMAD
 
-NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow.
+NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. Learn more on the [archive file structure](https://nomad-lab.eu/prod/v1/test/docs/explanation/data.html#archive-files-a-shared-entry-structure) from official NOMAD documentation. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow.
path: docs/custom.md
user: login: ndaelman-hu
body: "Learn more **about** the archive file structure **in** the official NOMAD documentation."

I'd put the link on "official NOMAD documentation", but that's less pressient.
created_at: 2025-03-13T15:04:46Z
author_association: COLLABORATOR
diff_hunk: @@ -151,65 +150,53 @@ You can now create analogous files `create_box.archive.yaml`, `insert_water.arch
 ??? success "`create_box.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Create box'
-          description: 'The initial simulation box is created.'
-          Files:
-          - file: 'Custom_ELN_Entries/box.gro'
-              description: 'An empty structure file with the box vectors.'
-    ```
-
-??? success "`insert_water.archive.yaml`"
-
-    ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Create box'
+      description: 'The initial simulation box is created.'
+      Files:
+      - file: 'Custom_ELN_Entries/box.gro'
+        description: 'An empty structure file with the box vectors.'
     ```
 
 ??? success "`insert_water.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Insert water'
+      description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
+      Files:
+      - file: 'Custom_ELN_Entries/water.gro'
+        description: 'The structure file for simulation input.'
     ```
 
 ??? success "`workflow_parameters.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
-          name: 'Workflow Parameters'
-          description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
+    data:
+      m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
+      name: 'Workflow Parameters'
+      description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
     ```
 
 ??? success "`workflow_scripts.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Workflow Scripts'
-          description: 'All the scripts run during setup of the MD simulation.'
-          Files:
-          - file: 'Custom_ELN_Entries/workflow_script_1.py'
-              description: 'Creates the simulation box and inserts water molecules.'
-          - file: 'Custom_ELN_Entries/workflow_script_2.py'
-              description: 'Creates the appropriate force field files for the simulation engine.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Workflow Scripts'
+      description: 'All the scripts run during setup of the MD simulation.'
+      Files:
+      - file: 'Custom_ELN_Entries/workflow_script_1.py'
+        description: 'Creates the simulation box and inserts water molecules.'
+      - file: 'Custom_ELN_Entries/workflow_script_2.py'
+        description: 'Creates the appropriate force field files for the simulation engine.'
     ```
 
 ## Creating a custom workflow in NOMAD
 
-NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow.
+NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. Learn more on the [archive file structure](https://nomad-lab.eu/prod/v1/test/docs/explanation/data.html#archive-files-a-shared-entry-structure) from official NOMAD documentation. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow.
path: docs/custom.md
user: login: ndaelman-hu
body: I think your addition is good, but it does break up the thought flow. Maybe at the end of the paragraph?
created_at: 2025-03-13T15:06:22Z
author_association: COLLABORATOR
diff_hunk: @@ -30,7 +30,7 @@ _Your Approach:_
 
 You have performed some vibrational analysis of the DFT configurations obtained from your simulations. The results are shown below. Create a file `result-vibrational-analysis-DFT.csv` to store the results:
 
-```
+```txt
 electron_density,oh_stretch_frequency
 au,1/cm
path: docs/workflows.md
user: login: ndaelman-hu
body: Esma mentioned removing "a.u." for arbitrary units, right?
Btw, electron density has dimensions...
created_at: 2025-03-13T15:08:13Z
author_association: COLLABORATOR
diff_hunk: @@ -129,8 +129,8 @@ After you have completed the publishing, save the `entry_id` to your `PIDs.json`
   "entry_ids": {
     "md-workflow": "<your md workflow entry id from Part 1>",
     "DFT": ["<your list of dft entry ids from above>"],
-    "setup-workflow": "",
-    "parameters": "<your workflow parameters entry id here>",
+    "setup-workflow": "<your setup workflow entry id from Part 3>",
+    "parameters": "<your workflow parameters entry id from Part 3>",
     "analysis": "<copy the vibrational analysis entry id here>"
path: docs/workflows.md
user: login: ndaelman-hu
body: also swap "here" with the relevant part?
created_at: 2025-03-13T15:08:58Z
author_association: COLLABORATOR
diff_hunk: @@ -310,68 +310,68 @@ gv.d3(
 
 We see that our output graph looks signficantly different than the input. That's because `nomad-utility-workflow` is automatically adding some default inputs/outputs to ensure the proper node connections within the workflow visualizer. For nodes without an `entry_type`, these default connections work by simply adding inputs/outputs that point to the mainfile of one of the nodes connected by an edge in the graph.
 
-Open the generated `project_workflow.archive.yaml`:
+??? success "example `project_workflow.archive.yaml`"
path: docs/workflows.md
user: login: ndaelman-hu
body: hard to check this section: git kinda spasmed out here :p
created_at: 2025-03-13T15:10:54Z
author_association: COLLABORATOR
diff_hunk: @@ -14,8 +14,8 @@
 
 *Your Approach:* Use the NOMAD workflow utility plugin!
 
-!!! NOTE
-    When using the NOMAD workflow utility plugin, be sure to execute all the commands in a jupyter notebook or in the same python session.
+!!! Warning "Attention"
+    The exercises have to be performed in a jupyter notebook (provided below) or in the same terminal/python session to retain the imported packages and defined variables during each step. 
path: docs/api.md
user: login: andreaa93
body: 👍🏼 
created_at: 2025-03-13T15:17:35Z
author_association: COLLABORATOR
diff_hunk: @@ -125,13 +124,13 @@ The section `AnnotationFile` contains 2 quantities `file` and `description` for
 
 ??? tip "More on custom schemas"
 
-    The YAML approach is a quick and dirty way to customize your NOMAD entries. It doesn't allow for complete integration of custom defined quantities within the database bacause the schema is injested via YAML file while NOMAD platform is running, in contrast to the quantities belonging to schemas organized in **plugins** (python packages) and installed in NOMAD during deployment. See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
+    The YAML approach is a quick and dirty way to customize your NOMAD entries. It doesn't allow for complete integration of custom defined quantities within the database search tools to avoid uncontrolled proliferation of schemas that would be detrimental for data FAIRness. Seamless integration of new quantities happens when schemas are organized in **plugins** (python packages) and installed in NOMAD during deployment. See [NOMAD Docs > How to write a YAML schema package](https://nomad-lab.eu/prod/v1/test/docs/howto/customization/basics.html){:target="_blank"} for more details about defining custom schemas in this way.
path: docs/custom.md
user: login: andreaa93
body: 👍🏼 
created_at: 2025-03-13T15:21:42Z
author_association: COLLABORATOR
diff_hunk: @@ -151,65 +150,53 @@ You can now create analogous files `create_box.archive.yaml`, `insert_water.arch
 ??? success "`create_box.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Create box'
-          description: 'The initial simulation box is created.'
-          Files:
-          - file: 'Custom_ELN_Entries/box.gro'
-              description: 'An empty structure file with the box vectors.'
-    ```
-
-??? success "`insert_water.archive.yaml`"
-
-    ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Create box'
+      description: 'The initial simulation box is created.'
+      Files:
+      - file: 'Custom_ELN_Entries/box.gro'
+        description: 'An empty structure file with the box vectors.'
     ```
 
 ??? success "`insert_water.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Insert water'
-          description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
-          Files:
-          - file: 'Custom_ELN_Entries/water.gro'
-              description: 'The structure file for simulation input.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Insert water'
+      description: 'Water is inserted into the simulation box, creating the structure file for simulation input.'
+      Files:
+      - file: 'Custom_ELN_Entries/water.gro'
+        description: 'The structure file for simulation input.'
     ```
 
 ??? success "`workflow_parameters.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
-          name: 'Workflow Parameters'
-          description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
+    data:
+      m_def: nomad.datamodel.metainfo.eln.ElnBaseSection
+      name: 'Workflow Parameters'
+      description: 'This is a description of the overall workflow parameters, or alternatively standard workflow specification...'
     ```
 
 ??? success "`workflow_scripts.archive.yaml`"
 
     ```yaml
-        data:
-          m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
-          name: 'Workflow Scripts'
-          description: 'All the scripts run during setup of the MD simulation.'
-          Files:
-          - file: 'Custom_ELN_Entries/workflow_script_1.py'
-              description: 'Creates the simulation box and inserts water molecules.'
-          - file: 'Custom_ELN_Entries/workflow_script_2.py'
-              description: 'Creates the appropriate force field files for the simulation engine.'
+    data:
+      m_def: '../upload/raw/Custom_ELN_Entries/ELNFiles.archive.yaml#ELNAnnotatedFiles'
+      name: 'Workflow Scripts'
+      description: 'All the scripts run during setup of the MD simulation.'
+      Files:
+      - file: 'Custom_ELN_Entries/workflow_script_1.py'
+        description: 'Creates the simulation box and inserts water molecules.'
+      - file: 'Custom_ELN_Entries/workflow_script_2.py'
+        description: 'Creates the appropriate force field files for the simulation engine.'
     ```
 
 ## Creating a custom workflow in NOMAD
 
-NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow.
+NOMAD allows users to connect entries into a workflow, i.e., a directed graph structure. This is achieved using the same parsing functionality as demonstrated with the custom schemas above. In this case, we simply populate the `workflow2` section instead of the `data` section. Learn more on the [archive file structure](https://nomad-lab.eu/prod/v1/test/docs/explanation/data.html#archive-files-a-shared-entry-structure) from official NOMAD documentation. When uploaded to NOMAD, a new _workflow_ entry will be created, with references to each of the workflow tasks, and also an interactive workflow graph for easy navigation of the entire workflow.
path: docs/custom.md
user: login: andreaa93
body: 👍🏼 
created_at: 2025-03-13T15:22:41Z
author_association: COLLABORATOR
diff_hunk: @@ -30,7 +30,7 @@ _Your Approach:_
 
 You have performed some vibrational analysis of the DFT configurations obtained from your simulations. The results are shown below. Create a file `result-vibrational-analysis-DFT.csv` to store the results:
 
-```
+```txt
 electron_density,oh_stretch_frequency
 au,1/cm
path: docs/workflows.md
user: login: andreaa93
body: I'll go for "e/A³"
created_at: 2025-03-13T15:24:34Z
author_association: COLLABORATOR
diff_hunk: @@ -129,8 +129,8 @@ After you have completed the publishing, save the `entry_id` to your `PIDs.json`
   "entry_ids": {
     "md-workflow": "<your md workflow entry id from Part 1>",
     "DFT": ["<your list of dft entry ids from above>"],
-    "setup-workflow": "",
-    "parameters": "<your workflow parameters entry id here>",
+    "setup-workflow": "<your setup workflow entry id from Part 3>",
+    "parameters": "<your workflow parameters entry id from Part 3>",
     "analysis": "<copy the vibrational analysis entry id here>"
path: docs/workflows.md
user: login: andreaa93
body: this is added during the current step. So in analogy to the previous PID.json filling, I used this phrasing
created_at: 2025-03-13T15:26:01Z
author_association: COLLABORATOR
diff_hunk: @@ -310,68 +310,68 @@ gv.d3(
 
 We see that our output graph looks signficantly different than the input. That's because `nomad-utility-workflow` is automatically adding some default inputs/outputs to ensure the proper node connections within the workflow visualizer. For nodes without an `entry_type`, these default connections work by simply adding inputs/outputs that point to the mainfile of one of the nodes connected by an edge in the graph.
 
-Open the generated `project_workflow.archive.yaml`:
+??? success "example `project_workflow.archive.yaml`"
path: docs/workflows.md
user: login: andreaa93
body: no worries, I still need to clean it up after today's discussions
created_at: 2025-03-13T15:26:46Z
author_association: COLLABORATOR

PR comments:
user: login: andreaa93
created_at: 2025-03-13T14:03:59Z
body: @ndaelman-hu just some fixes. Will move the "remove preliminary draft banner" to later on.

Please approve it, if it looks good for you
author_association: COLLABORATOR
user: login: andreaa93
created_at: 2025-03-13T15:27:49Z
body: @ndaelman-hu done! 
author_association: COLLABORATOR