From ef8bb461fa4de49c049935f38afc0404fa7fc75a Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Wed, 14 Jan 2026 18:41:59 +0100 Subject: [PATCH 1/3] Updated installation instructions to have direct dependencies in the pyproject.toml. --- docs/getting-started/installation.md | 28 ++++++++++++++++++++++++++-- pyproject.toml | 12 ++++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 8a777b39..af22ec0e 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,4 +1,28 @@ Installation -====== +============ -To write... +Since the code is still under development the best option to get the latest version is to install directly from github. + +1. Clone the repository. The repository uses submodules so they also need to be initialized. This can be done in the same step by including ``--recurse-submodules``. + + ``` + git clone --recurse-submodules https://github.com/python-accelerator-middle-layer/pyaml.git + ``` + +2. Make a virtual environment and activate it. It needs to use >= Python 3.11. + +3. Depending on which bindings you want to use for the control system you need to install including different dependencies. + + The available bindings are: + + - **tango-pyaml**: For TANGO. + + ``` + pip install .[tango-pyaml] + ``` + + - **pyaml-cs-oa**: For TANGO or EPICS using `ophyd-async`. + + ``` + pip install .[pyaml-cs-oa] + ``` diff --git a/pyproject.toml b/pyproject.toml index 54bdaa63..306c9f19 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,6 +15,9 @@ exclude = [ [tool.hatch.build.targets.wheel] packages = ["pyaml"] +[tool.hatch.metadata] +allow-direct-references = true + [project] name = "accelerator-middle-layer" description = "Python Accelerator Middle Layer" @@ -50,6 +53,15 @@ dependencies = [ ] [project.optional-dependencies] + +tango-pyaml = [ + "tango-pyaml @ git+https://github.com/python-accelerator-middle-layer/tango-pyaml.git" +] + +pyaml-cs-oa = [ + "pyaml-cs-oa @ git+https://github.com/python-accelerator-middle-layer/pyaml-cs-oa.git" +] + test = [ "pytest>=7.4", "pytest-cov>=3.0", From 45edbd06e6cea0d2ac20127d1cea9820043a6508 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Mon, 19 Jan 2026 16:13:48 +0100 Subject: [PATCH 2/3] Updated installation instructions everywhere for both user and developer installations. --- README.md | 51 ++++++------------- docs/getting-started/installation.md | 73 +++++++++++++++++++++++----- pyproject.toml | 10 ++-- 3 files changed, 82 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index e4b202fe..37e9b2a4 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,32 @@ [![Documentation Status](https://readthedocs.org/projects/pyaml/badge/?version=latest)](https://pyaml.readthedocs.io/en/latest/?badge=latest) ![Current release](https://img.shields.io/github/v/tag/python-accelerator-middle-layer/pyaml) -# pyAML: Python Accelerator Middle Layer +# Python Accelerator Middle Layer -Disclaimer: the pyAML software is still under development. +Python Accelerator Middle Layer (pyAML) is a joint technology platform for design, commissioning and operation of particle accelerators. -This repository is pyAML core. It is control system independent and provides the main functionality of pyAML (device abstraction for magnets, bpms, etc.; access to simulator (pyAT) and abstract implementation for control system). It is intended to be used together with a package that implements control system specific interface. +The code is still under development. The features include among others: -If you want to only tests for your machine and not develop, you shouldn't install this package. Instead go to the package for the bindings and install that one. It will install this package automatically. +- A control system agnostic interface to interact with the accelerator. +- Same interface to different backends: live accelerator, virtual accelerator and simulator. +- Machine independence allowing configuration of different type of accelerators and facility specific naming conventions. +- Unit conversions. +- Automatic generation of metadata and standardized format for measurement data. +- A set of standard applications and a framework for developing new applications. + +**This repository is for the core of pyAML.** It is control system independent and provides the core functionality of pyAML. It is intended to be used together with a package that implements the control system specific interface. Available packages for bindings: TANGO: [tango-pyaml](https://github.com/python-accelerator-middle-layer/tango-pyaml) TANGO or EPICS: [pyaml-cs-oa](https://github.com/python-accelerator-middle-layer/pyaml-cs-oa) -#### Developer Installation - -1. Clone the repository. You need to also update the submodules. - - ``` - cd pyaml - git submodule update --init --recursive - ``` -2. Create a virtual environment and activate it -3. Install the package in editable mode: - - ``` - pip install -e . - ``` -4. Install the development dependencies and pre-commit hooks - - ``` - pip install -e .[dev] - pre-commit install - ``` - -5. If you want to try the examples using the control system bindings you also need to install those. See: - - TANGO: [tango-pyaml](https://github.com/python-accelerator-middle-layer/tango-pyaml) - TANGO or EPICS: [pyaml-cs-oa](https://github.com/python-accelerator-middle-layer/pyaml-cs-oa) - -6. If you want to run tests manually using the TANGO bindings without requiring a live machine you can also install the the Dummy TANGO control system available in tests/dummy-cs/tango. It is a simple emulation that allows to check the interface to the control system. The implemented control system doesn't do anything but it is only intended for tests during the development. +### Installation +Installation instructions for both user and development installation can be found in the [documentation](https://pyaml.readthedocs.io/en/latest/?badge=latest) #### Documentation -The documentation is hosted on Read the Docs: [pyaml](https://pyaml.readthedocs.io/en/latest/?badge=latest). - -#### Examples +The documentation is available [here](https://pyaml.readthedocs.io/en/latest/?badge=latest). -Examples are available in the `examples` folder of the repository. -Additionally, in the documentation there are example Jupyter notebooks available. +In the documentation there is both examples and Jupyter notebooks available for how to use the package. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index af22ec0e..46ef49c3 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,9 +1,49 @@ Installation -============ +================== -Since the code is still under development the best option to get the latest version is to install directly from github. +## User Installation -1. Clone the repository. The repository uses submodules so they also need to be initialized. This can be done in the same step by including ``--recurse-submodules``. +The latest release can be installed from PyPI. If you want to communicate with a control system you in addition need to install the bindings you want by specifing extras. + +You need at least Python 3.11. + +**Remember to always install in a virtual environment to avoid breaking your Python environment.** + +### Installing without Control System Bindings + + +For example if you just want to use the simulator. + +``` +pip install accelerator-middle-layer +``` + + +### Installing with Control System Bindings + +Available options for installing with control system bindings are: + +- `tango-pyaml` for the tango-pyaml bindings. +- `cs-oa-epics` for `ophyd-async` bindings with both EPICS channel and PV access. +- `cs-oa-tango` for `ophyd-async` bindings for TANGO. + +Example usage: + +``` +pip install accelerator-middle-layer[cs-oa-epics] +``` + +## Developer Installation + +To do development work you need to clone the source code from GitHub and install in editable mode. + +**Note: if you are not a maintainer of the code and have write permissions to the repository you need to first fork the repository.** + +1. Clone the repository (or your fork) + + The repository uses submodules so they also need to be initialized. This can be done in the same step by including ``--recurse-submodules``. + + Example usage: ``` git clone --recurse-submodules https://github.com/python-accelerator-middle-layer/pyaml.git @@ -11,18 +51,25 @@ Since the code is still under development the best option to get the latest vers 2. Make a virtual environment and activate it. It needs to use >= Python 3.11. -3. Depending on which bindings you want to use for the control system you need to install including different dependencies. +3. Install the code in editable mode including development dependencies. - The available bindings are: + ``` + cd pyaml + pip install -e .[dev] + ``` + +4. Install the pre-commit hooks. + + ``` + pre-commit install + ``` - - **tango-pyaml**: For TANGO. +5. Install control system bindings *(optional)* - ``` - pip install .[tango-pyaml] - ``` + If you want to use control system bindings you need to also install the package for the binding you want to use. Follow the installation instructions in the corresponding repository. + + If you want to do development work on the bindings they need to be installed in editable mode, but if not you can install the latest release from PyPI. - - **pyaml-cs-oa**: For TANGO or EPICS using `ophyd-async`. +6. Install dummy control system for TANGO *(optional)* - ``` - pip install .[pyaml-cs-oa] - ``` + If you want to test the TANGO bindings without requiring a live machine or virtual accelerator you can install the dummy TANGO control system available in `tests/dummy-cs/tango`. It is a simple emulation that allows to check the interface to the control system. The control system doesn't do anything but is only intended for tests during development. diff --git a/pyproject.toml b/pyproject.toml index 306c9f19..122b5978 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,11 +55,15 @@ dependencies = [ [project.optional-dependencies] tango-pyaml = [ - "tango-pyaml @ git+https://github.com/python-accelerator-middle-layer/tango-pyaml.git" + "tango-pyaml", ] -pyaml-cs-oa = [ - "pyaml-cs-oa @ git+https://github.com/python-accelerator-middle-layer/pyaml-cs-oa.git" +cs-oa-epics = [ + "pyaml-cs-oa[epics]", +] + +cs-oa-tango = [ + "pyaml-cs-oa[tango]", ] test = [ From 1b334992fbca61d98f0f16438c866af4e503e80e Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Mon, 19 Jan 2026 16:17:55 +0100 Subject: [PATCH 3/3] Fixed grammar in README. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 37e9b2a4..4615591b 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,10 @@ TANGO or EPICS: [pyaml-cs-oa](https://github.com/python-accelerator-middle-layer ### Installation -Installation instructions for both user and development installation can be found in the [documentation](https://pyaml.readthedocs.io/en/latest/?badge=latest) +Installation instructions for both user and development installation can be found in the [documentation](https://pyaml.readthedocs.io/en/latest/?badge=latest). #### Documentation The documentation is available [here](https://pyaml.readthedocs.io/en/latest/?badge=latest). -In the documentation there is both examples and Jupyter notebooks available for how to use the package. +In the documentation there are both examples and Jupyter notebooks available for how to use the package.