DiamondLightSource · ptsOSL · Sep 29, 2025 · Jul 8, 2025 · Jul 15, 2025 · Jul 15, 2025
diff --git a/.copier-answers.yml b/.copier-answers.yml
@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 4.0.1
+_commit: 4.3.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: tobyn.nicholls@diamond.ac.uk
 author_name: Tobyn Nicholls
@@ -9,10 +9,11 @@ component_type: service
 description: Diamond virtual accelerator
 distribution_name: virtac
 docker: true
+docker_debug: false
 docs_type: sphinx
 git_platform: github.com
 github_org: DiamondLightSource
 package_name: virtac
-pypi: true
+pypi: false
 repo_name: virtac
 type_checker: mypy
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
 
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/4.0.1/how-to.html).
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/4.3.0/how-to.html).
diff --git a/.github/workflows/_docs.yml b/.github/workflows/_docs.yml
@@ -45,7 +45,7 @@ jobs:
         run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
 
       - name: Publish Docs to gh-pages
-        if: github.ref_type == 'tag' || github.ref_name == 'main'
+        if: github.ref_type == 'tag' || github.ref_name == 'main' || github.ref_name == 'dev'
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0

diff --git a/.github/workflows/_pypi.yml b/.github/workflows/_pypi.yml
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -44,13 +44,7 @@ jobs:
 
   dist:
     uses: ./.github/workflows/_dist.yml
-
-  pypi:
-    needs: [dist, test]
-    if: github.ref_type == 'tag'
-    uses: ./.github/workflows/_pypi.yml
-    permissions:
-      id-token: write
+
 
   release:
     needs: [dist, test, docs]

diff --git a/Dockerfile b/Dockerfile
@@ -1,6 +1,6 @@
 # The devcontainer should use the developer target and run as root with podman
 # or docker with user namespaces.
-ARG PYTHON_VERSION=latest
+ARG PYTHON_VERSION=3.11
 FROM python:${PYTHON_VERSION} AS developer
 
 # Add any system dependencies for the developer/build environment here
@@ -14,8 +14,21 @@ COPY . /virtac/
 # Set up a virtual environment and put it in PATH
 RUN python -m venv /venv
 ENV PATH=/venv/bin:$PATH
-RUN pip install .
+ENV EPICS_CA_SERVER_PORT=8064
+ENV EPICS_CA_REPEATER_PORT=8065
 
+# The build stage installs the context into the venv
+FROM developer AS build
+# Requires buildkit 0.17.0
+COPY --chmod=o+wrX . /workspaces/virtac
+WORKDIR /workspaces/virtac
+RUN touch dev-requirements.txt && pip install -c dev-requirements.txt .
+
+# The runtime stage copies the built venv into a slim runtime container
+FROM python:${PYTHON_VERSION}-slim AS runtime
+# Add apt-get system dependecies for runtime here if needed
+COPY --from=build /venv/ /venv/
+ENV PATH=/venv/bin:$PATH
 ENV EPICS_CA_SERVER_PORT=8064
 ENV EPICS_CA_REPEATER_PORT=8065
 

diff --git a/README.md b/README.md
@@ -1,6 +1,5 @@
 [![CI](https://github.com/DiamondLightSource/virtac/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/virtac/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/DiamondLightSource/virtac/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/virtac)
-[![PyPI](https://img.shields.io/pypi/v/virtac.svg)](https://pypi.org/project/virtac)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 # virtac
@@ -12,10 +11,11 @@ This module contains all of the diamond specific configuration to build the diam
 
 Source          | <https://github.com/DiamondLightSource/virtac>
 :---:           | :---:
-PyPI            | `pip install virtac`
-Docker          | `docker run ghcr.io/diamondlightsource/virtac:latest`
+Docker          | `docker run -it --network=host ghcr.io/diamondlightsource/virtac:latest`
 Documentation   | <https://diamondlightsource.github.io/virtac>
 Installation    | <https://diamondlightsource.github.io/virtac/tutorials/installation>
 Releases        | <https://github.com/DiamondLightSource/virtac/releases>
 
 <!-- README only content. Anything below this line won't be included in index.md -->
+
+The github pages documentation is automatically updated on pushes to the main and dev branches and also on tagged releases.
diff --git a/docs/conf.py b/docs/conf.py
@@ -49,6 +49,8 @@
     "sphinx_design",
     # So we can write markdown files
     "myst_parser",
+    # For autodocumenting argparse based CLIs
+    "sphinxcontrib.programoutput",
 ]
 
 # So we can use the ::: syntax
@@ -74,6 +76,8 @@
     ("py:class", "number"),
     ("py:class", "pythonSoftIoc.RecordWrapper"),
     ("py:class", "pytac.lattice.Lattice"),
+    ("py:class", "pytac.element.Element"),
+    ("py:class", "CSVData"),
     ("py:exc", "pytac.FieldException"),
     ("py:exc", "pytac.ControlSystemException"),
     ("py:exc", "pytac.HandleException"),
@@ -129,6 +133,8 @@
 # docs in the python documentation.
 intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
 
+intersphinx_disabled_reftypes = ["*"]
+
 # A dictionary of graphviz graph attributes for inheritance diagrams.
 inheritance_graph_attrs = {"rankdir": "TB"}
 
@@ -174,13 +180,7 @@
     },
     "use_edit_page_button": True,
     "github_url": f"https://github.com/{github_user}/{github_repo}",
-    "icon_links": [
-        {
-            "name": "PyPI",
-            "url": f"https://pypi.org/project/{project}",
-            "icon": "fas fa-cube",
-        }
-    ],
+    "icon_links": [{}],
     "switcher": {
         "json_url": switcher_json,
         "version_match": version,

diff --git a/docs/how-to/update_csv_files.md b/docs/how-to/update_csv_files.md
@@ -0,0 +1,12 @@
+# Update CSV Files
+
+Use the CLI to recreate the csv files. This runs create_csv.py and reads data from PVs on port 5064, so ensure you have configured your CA ports to 50XX.
+
+You can run create_csv with the default arguments and the correct ringmode, eg:
+
+:::{code-block} bash
+create_csv I04
+:::
+
+```{program-output} create_csv -h
+```
diff --git a/docs/tutorials.md b/docs/tutorials.md
@@ -6,6 +6,5 @@ Tutorials for installation and typical usage. New users start here.
 :maxdepth: 1
 :glob:
 
-tutorials/installation
-tutorials/virtac_example
+tutorials/*
 ```
diff --git a/docs/tutorials/overview.md b/docs/tutorials/overview.md
@@ -0,0 +1,76 @@
+# Overview
+
+## What is the Virtac?
+
+The Diamond Virtual Accelerator (Virtac for short) was created to simulate the high level controls interface to the real accelerator, mostly the storage ring. There are three main parts:
+
+1. An EPICS IOC which aims to faithfully reproduce the PVs available on the real machine and their behavior.
+2. A pytac lattice which contains the same elements (dipoles, quadrupoles, etc) as the real machine and is updated via the aforementioned PV interface.
+3. A pyAT simulation which is updated from the pytac lattice and indirectly from the Virtac PV interface.
+
+### 1. PV interface
+
+The Virtac provides over 4000 PVs which allow you to control the Virtac and to read information about it using channel access. We use [PythonSoftIOC](https://diamondlightsource.github.io/pythonSoftIOC/master/tutorials/creating-an-ioc.html) to create the EPICS IOC. We use information from pytac (which in turn derives its data from matlab middlelayer) in addition to information contained in csv files to create PVs. The data in our csv files is largely created by reading PVs from the real machine, with some manually generated configuration.
+
+### 2. Pytac lattice
+
+[Pytac](https://pytac.readthedocs.io/en/latest/) is used to define the lattice which describes the layout of the storage ring. The lattice tracks over 2000 elements, including different types of dipoles, quadrupoles, sextupoles, drifts and bpms.
+
+Pytac supports many lattice modes, but the Virtac currently supports just three: 'DIAD', 'I04' and the Diamond 2 ringmode, '48'.
+
+### 3. pyAT simulation
+
+[pyAT](https://atcollab.github.io/at/p/index.html) is used to simulate the physics inside the particle accelerator. More specifically, we mostly use pyAT to simulate the path of a single electron around the storage ring. pyAT also contains a lattice, this is linked to and configured from the pytac lattice.
+
+Our main use-case of pyAT is to allow modifications of the lattice (such as setting magnet currents via the PV interface) and then calculating how these modifications affect the reference orbit of an electron travelling around the storage ring. This core premise allows us to test certain feedback algorithms against the Virtac by setting magnet currents, then reading bpm positions and repeating until we find an idealized orbit.
+
+### What can currently be tested against the Virtac?
+
+Currently the Virtac only simulates the storage ring, but this may change in the future.
+
+The main use-case is IOCs which write to magnet current PVs and then need to see what effect this has on the ring.
+
+We simulate the following magnet families:
+- Bends
+- Quadrupoles
+- Skew quadrupoles
+- Horizontal and vertical steerers/correctors
+- Horizontal and vertical ID trim coils
+- Chicanes
+- Sextupoles
+- Octupoles (for Diamond 2)
+- Combined dipole-quadrupoles (for Diamond 2)
+- Anti-bend dipoles (for Diamond 2)
+
+We simulate the following ring parameters and provide them as PVs:
+- BPM positions
+- Emittance
+- Tune
+
+Some of the things that we dont simulate:
+- The linac
+- The booster ring
+- The transfer lines
+- Particle injection
+- Bunches
+- Electrons outside of the reference orbit
+- Beam decay
+- Insertion devices (only the trim coils for ID corrections are simulated)
+
+With the default settings, the simulation can only be recalculated at a maximum rate of:
+- Approximately 2Hz for Diamond 1
+- Approximately 0.7Hz for Diamond 2
+
+### Apps currently being tested against the Virtac
+
+- Slow orbit feedback
+- Tune feedback
+- Vertical emittance feedback
+- Response matrix calculation
+
+### Future plans
+
+- Allow the Virtac to be run using the Diamond II lattice configuration
+- Simulate the booster to storage ring transfer line
+- Simulate electrons which do not follow the reference orbit, ie by giving them a non-zero initial position in the beam tube.
+- Reduce the simulation recalculation delay
diff --git a/docs/tutorials/using_virtac.md b/docs/tutorials/using_virtac.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua

		This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.

		For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/4.0.1/how-to.html).
		For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/4.3.0/how-to.html).