From 61a03e834181f14511534dd813cb808dd7828cfc Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 19:51:54 +0200 Subject: [PATCH 01/16] Add tip to read the explanation page before starting. --- docs/source/how-to/configuration/create-configuration.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 8c3fb74..e4574fc 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -1,6 +1,10 @@ # Create and Load Configuration -This guide shows how to write a pyAML configuration as a text file and load it into an `Accelerator`. The structure and syntax of the configuration are explained in detail in [Configuration Structure and Syntax](../../explanation/configuration). +This guide shows how to write a pyAML configuration as a text file and load it into an `Accelerator`. + +```{tip} +Read [Configuration Structure and Syntax](../../explanation/configuration) which explains the concepts and ideas behind the configuration before you start. +``` ## The Rule to Remember From 210ba64305548028e1788f87d998eeca75cae154 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 19:56:22 +0200 Subject: [PATCH 02/16] Add some more details to the introduction. --- docs/source/how-to/configuration/create-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index e4574fc..2307f9d 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -1,6 +1,6 @@ # Create and Load Configuration -This guide shows how to write a pyAML configuration as a text file and load it into an `Accelerator`. +This guide shows how to write a pyAML configuration as a text file and load it into an `Accelerator`. It gives recommendations for how to write it and list tools that are available to help. ```{tip} Read [Configuration Structure and Syntax](../../explanation/configuration) which explains the concepts and ideas behind the configuration before you start. @@ -9,7 +9,7 @@ Read [Configuration Structure and Syntax](../../explanation/configuration) which ## The Rule to Remember ```{important} -Each item of the configuration names a Python class in its `class` field. **Every other field is an argument of the constructor of that class**, with the same name. When an argument is an object, its value is a nested item with its own `class` field. +Each item of the configuration names a Python class in its `class` field. **Every other field is an argument of the constructor of that class**, with the same name as the field. When an argument is an object, its value is a nested item with its own `class` field. ``` Writing a configuration is therefore the same as writing the Python code that creates the objects, in YAML (or JSON) instead of Python. From 4064839f8c04fa069e78bcfc1ff1ec141f3e368c Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 20:23:08 +0200 Subject: [PATCH 03/16] Remove in the introduction that the guide is about text file since it also includes dictionary. --- docs/source/how-to/configuration/create-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 2307f9d..ed35e5e 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -1,6 +1,6 @@ # Create and Load Configuration -This guide shows how to write a pyAML configuration as a text file and load it into an `Accelerator`. It gives recommendations for how to write it and list tools that are available to help. +This guide shows how to write a pyAML configuration and load it into an `Accelerator`. It gives recommendations for how to write it and list tools that are available to help. ```{tip} Read [Configuration Structure and Syntax](../../explanation/configuration) which explains the concepts and ideas behind the configuration before you start. From f4197be4d1a5a6eed07e205575c8a08041231f2a Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 20:33:16 +0200 Subject: [PATCH 04/16] Update the rule to remember section to make it clearer how using a configuration differs from building objects yourself. --- docs/source/how-to/configuration/create-configuration.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index ed35e5e..9642dcc 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -8,11 +8,13 @@ Read [Configuration Structure and Syntax](../../explanation/configuration) which ## The Rule to Remember +The configuration consists of a set of items which tells pyAML which objects to build when loading the configuration. + ```{important} -Each item of the configuration names a Python class in its `class` field. **Every other field is an argument of the constructor of that class**, with the same name as the field. When an argument is an object, its value is a nested item with its own `class` field. +Each item of the configuration names a Python class in its `class` field. **Every other field is an argument of the constructor of that class** with the same name as the field and the value to pass to the constructor. When a constructor argument is an object, its value in the configuration is a nested item with its own `class` field. ``` -Writing a configuration is therefore the same as writing the Python code that creates the objects, in YAML (or JSON) instead of Python. +Writing and loading the configuration is the equivalent of writing the Python code that creates the objects yourself. The configuration just allows pyAML to create the objects for you. ## Find the Fields of a Class From 39485afe13768e967114f0bef0c6e9d90ec8d8f8 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 20:42:06 +0200 Subject: [PATCH 05/16] Update finding the fields section with content from moved from the configuration explanation. --- .../how-to/configuration/create-configuration.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 9642dcc..a3c8984 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -16,11 +16,14 @@ Each item of the configuration names a Python class in its `class` field. **Ever Writing and loading the configuration is the equivalent of writing the Python code that creates the objects yourself. The configuration just allows pyAML to create the objects for you. -## Find the Fields of a Class +## Finding the Accepted Fields -Before writing an item, look up the constructor arguments of its class. Any of these works: +Before writing an item, look up the constructor parameters of the class you want pyAML to build an object of. This can be done in several ways: -- `help()` in Python, which shows the constructor signature and describes each argument: +- Read the [API documentation](./../reference/index.md) of the class +- Use `help()` in Python since this shows the signature of the constructor and description of each parameter + +For example: ```python from pyaml.bpm.bpm import BPM @@ -39,10 +42,10 @@ Before writing an item, look up the constructor arguments of its class. Any of t # | ... ``` -- the [API documentation](https://pyaml.readthedocs.io/en/stable/) of the class, -- the `describe()` method of the schema in the [schema registry](./use-schema-registry.ipynb). +- Use the schema registry. The `describe()` method lists the fields of a registered class with their types. See [Use the Schema Registry](../how-to/configuration/use-schema-registry.ipynb). +- Use a JSON Schema in an external tool. See [JSON Schema Tools](../how-to/configuration/create-configuration.md#tools-that-help-writing-the-configuration). -Arguments without a default value (here `name`) are required fields; the others can be left out. +Parameters with a default value is optional and can be left out of the configuration if you wish. ## Write the Configuration File From 9616c0be9a9c7e94672a7c6b1f43a9dd59116739 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 21:49:40 +0200 Subject: [PATCH 06/16] Add that the configuration can be written as yaml, json or dict. --- docs/source/how-to/configuration/create-configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index a3c8984..5b7f819 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -5,6 +5,7 @@ This guide shows how to write a pyAML configuration and load it into an `Acceler ```{tip} Read [Configuration Structure and Syntax](../../explanation/configuration) which explains the concepts and ideas behind the configuration before you start. ``` +The configuration can be written as a text file in YAML or JSON or as a dictionary. ## The Rule to Remember From 33db49d569680c1e73626d3907341c4da1496f87 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 21:59:15 +0200 Subject: [PATCH 07/16] Change heading to make clear that the example is for using a text file since the dictionary option also exist. --- docs/source/how-to/configuration/create-configuration.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 5b7f819..92a6456 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -48,9 +48,11 @@ For example: Parameters with a default value is optional and can be left out of the configuration if you wish. -## Write the Configuration File +## Write Configuration as a Text File -Create a file, for example `accelerator.yaml`, with any text editor. The steps below build a small but complete configuration, using the names of the [test lattice](../../tutorials/functionality/01_create_accelerator). +Here an example is shown for how to create the configuration in a YAML file. The steps are similar if using JSON. The steps below build a small but complete configuration, using the names of the [test lattice](../../tutorials/functionality/01_create_accelerator). + +Create a file, for example `accelerator.yaml`, with any text editor. If you want the editor to suggest the fields, you can use VS Code together with a JSON Schema. See [Use JSON Schema in VS Code](../configuration/use-vscode-json-schema.md) for instructions. ### 1. The Accelerator From bfd9280c65ea0290945d1627f7e362307f6669f4 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 22:05:00 +0200 Subject: [PATCH 08/16] Update the facility and machine name. --- docs/source/how-to/configuration/create-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 92a6456..128dc1b 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -60,8 +60,8 @@ The root item is the `Accelerator`. Its required arguments are `facility`, `mach ```yaml class: pyaml.accelerator.Accelerator -facility: My facility -machine: sr +facility: my_facility +machine: storage_ring energy: 1.0e9 ``` From 0d5ad1dc2707a6bde62815c1cfcd819e8af3ddd5 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 25 Sep 2026 08:21:25 +0200 Subject: [PATCH 09/16] Update the section about control modes since some information wrong. --- .../configuration/create-configuration.md | 25 +++++-------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 128dc1b..e380443 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -67,9 +67,9 @@ energy: 1.0e9 ### 2. The Control Modes -Add the control modes as lists in `simulators` and `controls`. Their `name` is also the name used to access them (`accelerator.design`, `accelerator.live`). +Add the control modes as lists in `simulators` and `controls`. Their `name` is also the name used to access them, for example `accelerator.design`, `accelerator.live` etc. -A simulator needs the path to a lattice file. Use `${path:...}` so that the path is resolved relative to the [configuration root](../../explanation/configuration.md#configuration-root) and the lattice is not loaded as a configuration file: +A simulator needs the path to a lattice file. All [formats that can be loaded by pyAT](https://atcollab.github.io/at/p/api/at.load.html#module-at.load) works. If you use the JSON format, you need to use the `${path:...}` [resolver](../../explanation/configuration.md#resolvers) to avoid the lattice being loaded as if it was a configuration file. ```yaml simulators: @@ -78,31 +78,18 @@ simulators: lattice: ${path:lattice.json} ``` -A control system is given by the class of the bindings you use. Its arguments depend on the bindings, for example for `pyaml-cs-oa`: +A control system is given by the class of the bindings you use. The arguments depend on the bindings and catalog type you decide to use. The catalog describes how the keys used by the devices map to control-system signals. See [Control System Catalogs](../../explanation/catalog.md) for the different types of catalogs. + +For example for `pyaml-cs-oa` using a dynamic catalog for TANGO: ```yaml controls: - class: pyaml_cs_oa.controlsystem.OphydAsyncControlSystem name: live backend: tango - catalog: catalog.yaml -``` - -The catalog describes how the keys used by the devices map to control-system signals. It follows exactly the same rule. A static catalog for `pyaml-cs-oa` looks like this (one entry per key): - -```yaml -class: pyaml_cs_oa.static_catalog.StaticCatalog -entries: - - class: pyaml_cs_oa.static_catalog_entry.StaticCatalogEntry - key: AN01-AR/EM-QP/QF.01/magnetic_strength - device: - class: pyaml_cs_oa.tangoAtt.TangoAtt - attribute: AN01-AR/EM-QP/QF.01/magnetic_strength - unit: 1/m - # ... one entry for each key used in the configuration ``` -See [Control System Catalogs](../../explanation/catalog.md) for the different types of catalogs. If you only want to use the simulator, you can leave out `controls` entirely. +If you only want to use the simulator, you can leave out `controls` entirely. ### 3. The Devices From b6ee30aa2ef8a9360db7b80bbb9b59c846e934de Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 25 Sep 2026 08:26:03 +0200 Subject: [PATCH 10/16] Update full configuration to match other changes. --- .../how-to/configuration/create-configuration.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index e380443..98f5345 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -93,7 +93,9 @@ If you only want to use the simulator, you can leave out `controls` entirely. ### 3. The Devices -Add the elements of the machine in `devices`. For a magnet, the `model` argument is an object (the magnet model, which also handles the unit conversion), so it is written as a nested item: +Add the elements of the machine in `devices`. For a magnet, the `model` argument is an object (the magnet model, which also handles the unit conversion), so it is written as a nested item. + +The strings given to `physics`, `x_pos` and `y_pos` are keys looked up in the catalog of the control system. ```yaml devices: @@ -115,7 +117,7 @@ devices: y_pos: AN01-AR/DG-EPOS/BPM.01/y ``` -By default, the `name` of an element is also the name of the element in the lattice of the simulator. Use `lattice_names` if they differ. The strings given to `physics`, `x_pos` and `y_pos` are keys looked up in the catalog of the control system. +By default, the `name` of an element is also the name of the element in the lattice of the simulator. If you want to use a different name in pyAML, use `lattice_names` to map between pyAML and the lattice. ### 4. The Arrays @@ -140,8 +142,8 @@ Putting it all together: ```yaml class: pyaml.accelerator.Accelerator -facility: My facility -machine: sr +facility: my_facility +machine: storage_ring energy: 1.0e9 simulators: - class: pyaml.lattice.simulator.Simulator From 7c9436f25284dc65a370056f4f31aa2ac78294c5 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 25 Sep 2026 08:27:29 +0200 Subject: [PATCH 11/16] Update catalog in example to match previous changes. --- docs/source/how-to/configuration/create-configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 98f5345..19b5def 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -153,7 +153,6 @@ controls: - class: pyaml_cs_oa.controlsystem.OphydAsyncControlSystem name: live backend: tango - catalog: catalog.yaml devices: - class: pyaml.magnet.quadrupole.Quadrupole name: QF_001 @@ -185,7 +184,7 @@ arrays: ## Split the Configuration into Several Files -For a real machine the configuration becomes long. When the configuration is loaded from a file, any string value ending with `.yaml`, `.yml` or `.json` is replaced by the content of that file (this is how `catalog: catalog.yaml` above is loaded). Inside a list, if the file contains a list, its items are added to the parent list. For example, move the quadrupoles to `devices/quadrupoles.yaml`: +For a real machine the configuration becomes long. When the configuration is loaded from a file, any string value ending with `.yaml`, `.yml` or `.json` is replaced by the content of that file. Inside a list, if the file contains a list, its items are added to the parent list. For example, move the quadrupoles to `devices/quadrupoles.yaml`: ```yaml # devices/quadrupoles.yaml From 567e3414c4264888fc057f9a3f1d16b530ad37a8 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 25 Sep 2026 08:29:43 +0200 Subject: [PATCH 12/16] Update text about using own classes. --- docs/source/how-to/configuration/create-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 19b5def..95c2297 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -214,7 +214,7 @@ Values can also come from environment variables with `${env:NAME}`. See [Resolve ## Use Your Own Classes -The rule is not limited to pyAML classes. Any class that can be imported can be used in the configuration, for example a magnet model specific to your facility: +The configuration is not limited to pyAML classes. Any class that can be imported can be used in the configuration, for example a magnet model specific to your facility: ```python # my_facility/models.py From 0e1f53f0b8a9bc909fe79a8841a9750615168b75 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 25 Sep 2026 08:34:25 +0200 Subject: [PATCH 13/16] Update section about loading the config. --- docs/source/how-to/configuration/create-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 95c2297..4932121 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -234,7 +234,7 @@ model: ## Load the Configuration -Set the configuration root, which is the directory used to resolve relative paths, then load the file with `Accelerator.load()`: +Set the [configuration root](../../explanation/configuration.md#configuration-root), which is the directory used to resolve relative paths, then load the file with `Accelerator.load()`. ```python from pyaml.configuration import ROOT @@ -246,9 +246,9 @@ accelerator = Accelerator.load("accelerator.yaml") accelerator.design.magnets.get("Quadrupoles").strengths.get() ``` -If the control-system bindings are not installed or you only want to use the simulator, add `ignore_external=True`. The `controls` section is then skipped. +If the control-system bindings are not installed or you only want to use the simulator, add `ignore_external=True` and the `controls` section is skipped without having to remove it from the configuration. -The configuration can also be given as a nested dictionary with `Accelerator.from_dict()`, following the same rule: +The configuration can also be loaded as a nested dictionary with `Accelerator.from_dict()`. This also allows to write the configuration directly as a dictionary instead of a text file if you prefer. ```python import yaml From e87fa30b3fa5922f5ab5a8022f4b9428cf733837 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 25 Sep 2026 08:42:20 +0200 Subject: [PATCH 14/16] Update validation section since information in there was wrong. --- docs/source/how-to/configuration/create-configuration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 4932121..e6bd8c0 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -263,7 +263,9 @@ See the API documentation for the [Accelerator](https://pyaml.readthedocs.io/en/ ## Validate the Configuration -Each item is checked when it is created: a missing required field or an unknown field raises a `PyAMLConfigException` naming the class and the field. The whole configuration can also be validated before anything is created, which gives all errors at once: +If the classes you use have enabled validation during object creation (this is the default for all common pyAML classes), the configuration will be validated as part of creating the objects: a missing required field or an unknown field raises a `PyAMLConfigException` naming the class and the field. + +The whole configuration can also be validated before anything is created. ```python from pyaml.validation import SchemaRegistry From a49e578cb70538406765268e231512693f64ba63 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 25 Sep 2026 09:05:47 +0200 Subject: [PATCH 15/16] Update section about tools. --- .../configuration/create-configuration.md | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index e6bd8c0..7427139 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -7,6 +7,10 @@ Read [Configuration Structure and Syntax](../../explanation/configuration) which ``` The configuration can be written as a text file in YAML or JSON or as a dictionary. +```{note} +Tools are available to help writing the configuration. See [Tools That Help Writing the Configuration](../configuration/create-configuration.md#tools-that-help-writing-the-configuration) for the options. +``` + ## The Rule to Remember The configuration consists of a set of items which tells pyAML which objects to build when loading the configuration. @@ -44,7 +48,7 @@ For example: ``` - Use the schema registry. The `describe()` method lists the fields of a registered class with their types. See [Use the Schema Registry](../how-to/configuration/use-schema-registry.ipynb). -- Use a JSON Schema in an external tool. See [JSON Schema Tools](../how-to/configuration/create-configuration.md#tools-that-help-writing-the-configuration). +- Use a JSON Schema in an external tool. See [Tools That Help Writing the Configuration](../configuration/create-configuration.md#tools-that-help-writing-the-configuration) for the options. Parameters with a default value is optional and can be left out of the configuration if you wish. @@ -278,12 +282,18 @@ The configuration can also be validated without loading it, which is useful if y ## Tools That Help Writing the Configuration -Writing the file by hand is often the simplest way to start, but tools based on a [JSON Schema](../../explanation/schema_and_validation.md) can suggest the available fields and check their types while you write: +There are tools available to help to write and modify the configuration. They can suggest the fields and check their types while you write. The tools are under development and testing so new or other tools might be available in the future based on user feedback. + +Some of the tools are based on a [JSON Schema](https://json-schema.org). For information about JSON Schemas and how to generate them, see [Configuration Schemas and Validation](../../explanation/schema_and_validation.md) and [Generate JSON Schemas](./generate-json-schema.ipynb). + +Currently these tools are available: + +- [Use ConfigurationSchema](./use-configuration-schema.ipynb) objects to create the configuration in Python and export it as a dictionary or text file. This allows to program the configuration. - [Use a JSON Schema in VS Code](./use-vscode-json-schema.md) -- [Use the MetaConfigurator](./use-meta-configurator.md), a form-based editor in the browser -- [Use ConfigurationSchema](./use-configuration-schema.ipynb) objects to create the configuration in Python and export it as a dictionary or text file -AI coding assistants can also help: supply for example a lattice file, a description of the naming conventions of your control system, and the JSON Schema of the pyAML configuration. +- [Use the MetaConfigurator](./use-meta-configurator.md), a form-based editor in the browser -For information about JSON Schemas and how to generate them, see [Configuration Schemas and Validation](../../explanation/schema_and_validation.md) and [Generate JSON Schemas](./generate-json-schema.ipynb). +```{tip} +AI coding assistants can also help: supply for example a lattice file, a description of the naming conventions of your control system, and the JSON Schema of the pyAML configuration and ask it to write the configuration for you. +``` \ No newline at end of file From 15b65b7ba529b29e933b960d14dedbed6b558f0e Mon Sep 17 00:00:00 2001 From: Alexis Gamelin Date: Tue, 6 Oct 2026 17:38:51 +0200 Subject: [PATCH 16/16] Add a new tool pages --- .../configuration/create-configuration.md | 61 +++---------------- .../how-to/configuration/tools/index.md | 26 ++++++++ .../use-configuration-schema.ipynb | 2 +- .../{ => tools}/use-meta-configurator.md | 2 +- .../{ => tools}/use-vscode-json-schema.md | 0 .../validate-configuration.ipynb | 16 ++++- docs/source/how-to/index.md | 5 +- 7 files changed, 53 insertions(+), 59 deletions(-) create mode 100644 docs/source/how-to/configuration/tools/index.md rename docs/source/how-to/configuration/{ => tools}/use-configuration-schema.ipynb (99%) rename docs/source/how-to/configuration/{ => tools}/use-meta-configurator.md (98%) rename docs/source/how-to/configuration/{ => tools}/use-vscode-json-schema.md (100%) diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md index 7427139..a287b0c 100644 --- a/docs/source/how-to/configuration/create-configuration.md +++ b/docs/source/how-to/configuration/create-configuration.md @@ -1,6 +1,6 @@ # Create and Load Configuration -This guide shows how to write a pyAML configuration and load it into an `Accelerator`. It gives recommendations for how to write it and list tools that are available to help. +This guide shows how to write a pyAML configuration and load it into an `Accelerator` using a minimal example. ```{tip} Read [Configuration Structure and Syntax](../../explanation/configuration) which explains the concepts and ideas behind the configuration before you start. @@ -8,7 +8,7 @@ Read [Configuration Structure and Syntax](../../explanation/configuration) which The configuration can be written as a text file in YAML or JSON or as a dictionary. ```{note} -Tools are available to help writing the configuration. See [Tools That Help Writing the Configuration](../configuration/create-configuration.md#tools-that-help-writing-the-configuration) for the options. +Tools are available to help writing the configuration. See [Tools That Help Writing the Configuration](./tools/index.md) for the options. ``` ## The Rule to Remember @@ -25,7 +25,7 @@ Writing and loading the configuration is the equivalent of writing the Python co Before writing an item, look up the constructor parameters of the class you want pyAML to build an object of. This can be done in several ways: -- Read the [API documentation](./../reference/index.md) of the class +- Read the [API documentation](../../reference/index.md) of the class - Use `help()` in Python since this shows the signature of the constructor and description of each parameter For example: @@ -47,16 +47,16 @@ For example: # | ... ``` -- Use the schema registry. The `describe()` method lists the fields of a registered class with their types. See [Use the Schema Registry](../how-to/configuration/use-schema-registry.ipynb). -- Use a JSON Schema in an external tool. See [Tools That Help Writing the Configuration](../configuration/create-configuration.md#tools-that-help-writing-the-configuration) for the options. +- Use the schema registry. The `describe()` method lists the fields of a registered class with their types. See [Use the Schema Registry](./use-schema-registry.ipynb). +- Use a JSON Schema in an external tool. See [Tools That Help Writing the Configuration](./tools/index.md) for the options. Parameters with a default value is optional and can be left out of the configuration if you wish. ## Write Configuration as a Text File -Here an example is shown for how to create the configuration in a YAML file. The steps are similar if using JSON. The steps below build a small but complete configuration, using the names of the [test lattice](../../tutorials/functionality/01_create_accelerator). +Here an example is shown for how to create the configuration in a YAML file. The steps are similar if using JSON. The steps below build a small but complete configuration. -Create a file, for example `accelerator.yaml`, with any text editor. If you want the editor to suggest the fields, you can use VS Code together with a JSON Schema. See [Use JSON Schema in VS Code](../configuration/use-vscode-json-schema.md) for instructions. +Create a file, for example `accelerator.yaml`, with any text editor. If you want the editor to suggest the fields, you can use VS Code together with a JSON Schema. See [Use JSON Schema in VS Code](./tools/use-vscode-json-schema.md) for instructions. ### 1. The Accelerator @@ -208,10 +208,7 @@ and refer to it from the main file: ```yaml devices: - devices/quadrupoles.yaml - - class: pyaml.bpm.bpm.BPM - name: BPM_001 - x_pos: AN01-AR/DG-EPOS/BPM.01/x - y_pos: AN01-AR/DG-EPOS/BPM.01/y + # ... ``` Values can also come from environment variables with `${env:NAME}`. See [Resolvers](../../explanation/configuration.md#resolvers) for all options. @@ -254,46 +251,6 @@ If the control-system bindings are not installed or you only want to use the sim The configuration can also be loaded as a nested dictionary with `Accelerator.from_dict()`. This also allows to write the configuration directly as a dictionary instead of a text file if you prefer. -```python -import yaml - -with open("accelerator.yaml") as file: - config = yaml.safe_load(file) - -accelerator = Accelerator.from_dict(config) -``` +To validate the whole configuration before any object is created, add `validate=True`. See [Validate Configuration](./validate-configuration) for details. See the API documentation for the [Accelerator](https://pyaml.readthedocs.io/en/stable/api/pyaml.accelerator.html#module-pyaml.accelerator) for all options. - -## Validate the Configuration - -If the classes you use have enabled validation during object creation (this is the default for all common pyAML classes), the configuration will be validated as part of creating the objects: a missing required field or an unknown field raises a `PyAMLConfigException` naming the class and the field. - -The whole configuration can also be validated before anything is created. - -```python -from pyaml.validation import SchemaRegistry - -SchemaRegistry().discover() -accelerator = Accelerator.load("accelerator.yaml", validate=True) -``` - -The configuration can also be validated without loading it, which is useful if you maintain it separately from pyAML. See [Validate Configuration](./validate-configuration). - -## Tools That Help Writing the Configuration - -There are tools available to help to write and modify the configuration. They can suggest the fields and check their types while you write. The tools are under development and testing so new or other tools might be available in the future based on user feedback. - -Some of the tools are based on a [JSON Schema](https://json-schema.org). For information about JSON Schemas and how to generate them, see [Configuration Schemas and Validation](../../explanation/schema_and_validation.md) and [Generate JSON Schemas](./generate-json-schema.ipynb). - -Currently these tools are available: - -- [Use ConfigurationSchema](./use-configuration-schema.ipynb) objects to create the configuration in Python and export it as a dictionary or text file. This allows to program the configuration. - -- [Use a JSON Schema in VS Code](./use-vscode-json-schema.md) - -- [Use the MetaConfigurator](./use-meta-configurator.md), a form-based editor in the browser - -```{tip} -AI coding assistants can also help: supply for example a lattice file, a description of the naming conventions of your control system, and the JSON Schema of the pyAML configuration and ask it to write the configuration for you. -``` \ No newline at end of file diff --git a/docs/source/how-to/configuration/tools/index.md b/docs/source/how-to/configuration/tools/index.md new file mode 100644 index 0000000..c01d850 --- /dev/null +++ b/docs/source/how-to/configuration/tools/index.md @@ -0,0 +1,26 @@ +# Tools That Help Writing the Configuration + +There are tools available to help to write and modify the configuration. They can suggest the fields and check their types while you write. The tools are under development and testing so new or other tools might be available in the future based on user feedback. + +Some of the tools are based on a [JSON Schema](https://json-schema.org). For information about JSON Schemas and how to generate them, see [Configuration Schemas and Validation](../../../explanation/schema_and_validation.md) and [Generate JSON Schemas](../generate-json-schema.ipynb). + +Currently these tools are available: + +- [Use ConfigurationSchema](./use-configuration-schema.ipynb) objects to create the configuration in Python and export it as a dictionary or text file. This allows to program the configuration. + +- [Use a JSON Schema in VS Code](./use-vscode-json-schema.md) + +- [Use the MetaConfigurator](./use-meta-configurator.md), a form-based editor in the browser + +```{tip} +AI coding assistants can also help: supply for example a lattice file, a description of the naming conventions of your control system, and the JSON Schema of the pyAML configuration and ask it to write the configuration for you. +``` + +```{toctree} +:maxdepth: 1 +:hidden: + +use-configuration-schema +use-vscode-json-schema +use-meta-configurator +``` diff --git a/docs/source/how-to/configuration/use-configuration-schema.ipynb b/docs/source/how-to/configuration/tools/use-configuration-schema.ipynb similarity index 99% rename from docs/source/how-to/configuration/use-configuration-schema.ipynb rename to docs/source/how-to/configuration/tools/use-configuration-schema.ipynb index a46f34c..695faf5 100644 --- a/docs/source/how-to/configuration/use-configuration-schema.ipynb +++ b/docs/source/how-to/configuration/tools/use-configuration-schema.ipynb @@ -7,7 +7,7 @@ "source": [ "# Generate Configuration Using Configuration Schemas\n", "\n", - "This guide shows how to use `ConfigurationSchema` to create a configuration. This allows to program the configuration if you prefer instead of using any of the [options based on a JSON Schema](.//create-configuration.md)." + "This guide shows how to use `ConfigurationSchema` to create a configuration. This allows to program the configuration if you prefer instead of using any of the [options based on a JSON Schema](./index.md)." ] }, { diff --git a/docs/source/how-to/configuration/use-meta-configurator.md b/docs/source/how-to/configuration/tools/use-meta-configurator.md similarity index 98% rename from docs/source/how-to/configuration/use-meta-configurator.md rename to docs/source/how-to/configuration/tools/use-meta-configurator.md index 49e8126..6db9eaa 100644 --- a/docs/source/how-to/configuration/use-meta-configurator.md +++ b/docs/source/how-to/configuration/tools/use-meta-configurator.md @@ -6,7 +6,7 @@ Pre-generated schemas are available in [pyaml-schemas](https://github.com/python-accelerator-middle-layer/pyaml-schemas). These include the classes that are part of the pyAML ecosystem. -If you have facility specific classes that you want to include in your configuration, you can use the `SchemaRegistry` to generate a JSON Schema including them. See [Generate JSON Schemas](../configuration/generate-json-schema) for details. +If you have facility specific classes that you want to include in your configuration, you can use the `SchemaRegistry` to generate a JSON Schema including them. See [Generate JSON Schemas](../generate-json-schema) for details. The schema must describe the document you want to create. For example, a schema for a quadrupole is suitable for editing a quadrupole object, but not for editing a complete accelerator containing controls, simulators, and devices. diff --git a/docs/source/how-to/configuration/use-vscode-json-schema.md b/docs/source/how-to/configuration/tools/use-vscode-json-schema.md similarity index 100% rename from docs/source/how-to/configuration/use-vscode-json-schema.md rename to docs/source/how-to/configuration/tools/use-vscode-json-schema.md diff --git a/docs/source/how-to/configuration/validate-configuration.ipynb b/docs/source/how-to/configuration/validate-configuration.ipynb index 06cacfd..7b3b944 100644 --- a/docs/source/how-to/configuration/validate-configuration.ipynb +++ b/docs/source/how-to/configuration/validate-configuration.ipynb @@ -7,7 +7,21 @@ "source": [ "# Validate Configuration\n", "\n", - "To make sure that the input data provided to pyAML has the correct format, validation is important. The validation is by default automatically performed when loading a configuration into the `Accelerator`, but it can also be done separately if one wishes. This guide shows how to do that.\n", + "To make sure that the input data provided to pyAML has the correct format, validation is important.\n", + "\n", + "If the classes you use have enabled validation during object creation (this is the default for all common pyAML classes), the configuration is validated as part of creating the objects: a missing required field or an unknown field raises a `PyAMLConfigException` naming the class and the field.\n", + "\n", + "The whole configuration can also be validated before anything is created when loading it:\n", + "\n", + "```python\n", + "from pyaml.accelerator import Accelerator\n", + "from pyaml.validation import SchemaRegistry\n", + "\n", + "SchemaRegistry().discover()\n", + "accelerator = Accelerator.load(\"accelerator.yaml\", validate=True)\n", + "```\n", + "\n", + "The configuration can also be validated without loading it, which is useful if you maintain it separately from pyAML. This guide shows how to do that.\n", "\n", "For more details about schemas and the different types of validation, see [Configuration Schemas and Validation](./../../explanation/schema_and_validation.md).\n", "\n", diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md index 7a075ab..150b94b 100644 --- a/docs/source/how-to/index.md +++ b/docs/source/how-to/index.md @@ -25,10 +25,7 @@ configuration/create-configuration configuration/use-schema-registry configuration/validate-configuration configuration/generate-json-schema -configuration/use-configuration-schema -configuration/use-meta-configurator -configuration/use-vscode-json-schema - +configuration/tools/index ``` ```{toctree}