diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..16e009a --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +* text=auto +*.md text +*.rst text +*.rest text \ No newline at end of file diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..2b6579c --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,23 @@ +name: sphinx + +on: [push, workflow_call] + +jobs: + spellcheck: + runs-on: "windows-latest" + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: install requirements + run: pip install -e .[dev] + - name: run spellcheck + run: sphinx-build -E -a -W --keep-going -b spelling doc _build + build: + uses: ISISComputingGroup/reusable-workflows/.github/workflows/sphinx.yml@main + secrets: inherit + with: + deploy-branch: "docs" diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml new file mode 100644 index 0000000..45cdf9c --- /dev/null +++ b/.github/workflows/nightly.yml @@ -0,0 +1,9 @@ +name: nightly +on: + schedule: + - cron: "0 0 * * *" + workflow_dispatch: + +jobs: + nightly: + uses: ./.github/workflows/documentation.yml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d007e1c --- /dev/null +++ b/.gitignore @@ -0,0 +1,164 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/latest/usage/project/#working-with-version-control +.pdm.toml +.pdm-python +.pdm-build/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +.idea/ +.vscode/ + +.idea/* +.venv/ +ibex_developers_manual.egg-info/ +build/ +_build/ \ No newline at end of file diff --git a/README.md b/README.md index 32ff8e2..97cffd7 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,3 @@ # ibex_user_manual -See https://github.com/ISISComputingGroup/ibex_user_manual/wiki/ + +See https://isiscomputinggroup.github.io/ibex_user_manual diff --git a/doc/Device-Specific-Guidance.md b/doc/Device-Specific-Guidance.md new file mode 100644 index 0000000..f955a3d --- /dev/null +++ b/doc/Device-Specific-Guidance.md @@ -0,0 +1,12 @@ +# Device-specific guidance + +This page contains information for a user on specific devices. The devices on this page have caused trouble or have some subtleties. If you are having trouble with a device and it is not listed below please let us know which device and what your issues were so that we can document it below. + +```{toctree} +:maxdepth: 1 +:titlesonly: +:glob: + +device_specific/* +``` + diff --git a/doc/FAQ.rst b/doc/FAQ.rst new file mode 100644 index 0000000..4554358 --- /dev/null +++ b/doc/FAQ.rst @@ -0,0 +1,169 @@ +FAQ +### + +In this section of the IBEX user manual, we have compiled a list of frequently asked questions. If your question about IBEX is not answered below, please let us (the Experiment Controls team) know. If your question is likely to be asked by others, we'll add it to the list. + +.. contents:: **List of Frequently Asked Questions** + +IBEX Processes and Support +========================== + +.. _report_a_problem: + +How do I report a problem or get help with IBEX? +------------------------------------------------ + +**A:** For a non-urgent issue use the `Instrument Problem/Bug Report `_ page or email ISISExperimentControls@stfc.ac.uk + +When reporting a problem, it is helpful to include the version numbers of your IBEX Client and Server in your report. To view the version numbers select ``Help > About`` from the menu bar in the IBEX Client. + +For urgent issues call **1763** (RAL site landline or ZOOM phone) or **01235394488** + +How do I install IBEX Server? +----------------------------- + +To install the IBEX Server - see :ref:`installing_ibex_server`. + +How do I install IBEX Client? +----------------------------- + +To install IBEX Client - see :ref:`installing_ibex_client`. + +Can I run IBEX and SECI at the same time? +----------------------------------------- + +In a word - No. Running two control programs on any system is a bad idea - which program has control? If you were to run IBEX and SECI on the same system, the two would contend for control of individual devices. It would not be clear which device was controlled by which program. The results would be unpredictable. + +Which version of Python does IBEX use? +-------------------------------------- + +IBEX currently uses Python 3.11.2. + +Where can I learn about Python? +------------------------------- + +Python is the scripting language used by IBEX. `genie_python` is a python library implementing ISIS-specific functions. If you are new to Python, we suggest you consult the excellent :external+mantid:ref:`introduction_to_python` created by the Mantid team. + + +How do I view which new IBEX features have been requested or are being worked on? +--------------------------------------------------------------------------------- + +There are internal lists showing priorities available covering the work which will feed into IBEX, please ask the experiment controls group or your group leader if you need to see these. These lists give you an idea of the long term work, and the priorities at that level. +IBEX is released and deployed to each instrument at least once a year, with patches as required. To see what is being worked on for the next release, you will need to find the most recent PI project on https://github.com/orgs/ISISComputingGroup/projects, note that these are in the format PI_YYYY_MM, with the month being the one the PI starts in. +The shortest time scale we consider is a sprint, and you can view this information on GitHub at https://github.com/ISISComputingGroup/IBEX/projects/1. +There is also a long list of issues on GitHub that can be viewed at https://github.com/ISISComputingGroup/IBEX/issues. Please note, this is a rather long list and not very friendly to browse through unless you already know what you're looking for (e.g. a device name). + + +Running IBEX +============ + +How do I start IBEX Server? +--------------------------- + +To start IBEX Server - see :ref:`starting_ibex_server`. + +How do I stop IBEX Server? +-------------------------- + +To stop IBEX Server - see :ref:`stopping_ibex_server`. + +Can I switch from running IBEX to SECI and vice-versa? +------------------------------------------------------ + +Yes, it is possible to switch from running IBEX to SECI or to switch from SECI to IBEX, but you have to be careful. See :doc:`obsolete/Switching-Between-IBEX-and-SECI` for details. + +Can I write scripts to control my experiment? +--------------------------------------------- + +Yes, you can. Scripting in IBEX is done using python (with support from a library called genie_python). See :doc:`Scripting` for more details. + +What do I look at if there are no RAW frames when Collecting Data? +------------------------------------------------------------------ + +If when collecting data no raw frames are counted (see `Good / Raw` Frames on the dashboard) then: + +Timing is ISIS: + Either ISIS is off, or there is a problem with the ToF (ISIS) signal. Check other instruments to find out. + +Timing is SMP: + Chopper is not spinning, or there is a problem with the signal + +Consider swapping the timing source to help diagnose the problem. + +What do I look at if there are no GOOD frames when Collecting Data? +------------------------------------------------------------------- + +If there are RAW frames but no good frames then the count is being vetoed. Open the DAE perspective and select the Vetoes tab to see what is vetoing the frame. + +FIFO veto: + Too many counts in a frame, e.g. noisy detector, jaws opened too wide + +SMP veto: + chopper out of phase with ISIS, or no ISIS signal + +External veto{0-3}: + could be an additional chopper, the shutter or moderator + +Can I change what my graphs look like in the log plotter or OPI? +---------------------------------------------------------------- + +**Yes!** There are lots of setting exposed by the native control. These include graph title, axis font type and size, trace line colour, line type, and line width. To reach these settings for a graph in an OPI do the following: + +#. To show the toolbar on an OPI graph right click and select Show/Hide Graph Toolbar. +#. Then click the settings button (leftmost icon with a spanner and screwdriver on it) +#. Click on the tabs to find what you want to change. The graph is the first panel, axes on the second and traces (with a drop down to select for which trace) is on the third. + +To open the settings in a log plotter graph, just right click and click "Open Properties Panel". + +.. _faq_find_pv: + +How do I find a specific PV? +---------------------------- + +PVs in IBEX should all follow the naming convention as specified in :doc:`/concepts/PV-Naming-Conventions`. You can search for PVs that are available on your instrument by using the `Select PV` button in the :ref:`manage_configs_blocks`. Finally, if you can see the value that you want on an OPI you can hover over it to get the PV name or right click and `Show PV Info`. + +How do I set a value to change when I change configuration/component? +--------------------------------------------------------------------- + +This can be accomplished by using :ref:`manage_configs_pv_values`. + +Why are some blocks and their PV addresses greyed-out in the "Edit Configuration" dialogue box? +----------------------------------------------------------------------------------------------- + +This is because they are part of a `component` and can't be edited from a host configuration. To make changes to the "master" copy, open the relevant component from the menu `Configuration -> Components -> Edit Component`. See the note at the bottom of the :ref:`manage_configs_blocks` section for more information. + + +Scripting in IBEX +================= + +In the scripting view I don't want the arguments when I autocomplete +-------------------------------------------------------------------- + +In the scripting console type `g.` will show a list of possible genie_python commands. If you select one of these or type to narrow down the possibilities, pressing return will autocomplete the method name including the parameters. However, sometimes you will not want all the parameters, so instead of pressing press + , this will give only the function name without any parenthesis or arguments. + +When I load script I get an error complaining about unicodeescape +----------------------------------------------------------------- + +If you try to load a script and you get the following error: + +.. code-block:: + + >>> `g.load_script('c:\scripts\NiceScript.py')` + File "", line 1 + g.load_script('c:\scripts\NiceScript.py') + ^ + SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes in position 10-11: malformed \N character escape + +The problem is you have not escaped the string correctly, in python the slash character, `\\`, is an escape character used to create things like newline characters. In this command, the `\\N` is a newline character and is causing python trouble. You can either: + +#. Place an `r` before the string (called a raw string) this makes it ignore escapes except for quote marks + - ``g.load_script(r'c:\\scripts\\NiceScript.py')`` +#. Escape the slashes + - ``g.load_script('c:\\\\scripts\\\\NiceScript.py')`` +#. Just use the default script path so: + - ``g.load_script('NiceScript.py')`` + +Can I run scripts from Mantid? +----------------------------------------------------------------- + +`genie_python` - the library which provides convenience functions such as `cset` and `cget` in order to run scripts can be installed from `pip`, and is available on pypi under https://pypi.org/project/genie-python/ . \ No newline at end of file diff --git a/doc/Glossary.rst b/doc/Glossary.rst new file mode 100644 index 0000000..b37f8b5 --- /dev/null +++ b/doc/Glossary.rst @@ -0,0 +1,65 @@ +Glossary +######## + +.. glossary:: + + Axis + In IBEX, the term axis refers to a degree-of-freedom within an experimental system. See `Axes in IBEX `_ for more detail. + + Block + This is a named piece of information created by the user as part of an instrument configuration. + A block is essentially an alias to a process variable. A block can have logging enabled and + will then appear in the final data file. + + Blockserver + This is a Server element of the IBEX control system that is responsible for managing + a Block and also a Configuration. + + Client-Server + IBEX, like EPICS, is a client-server system. In such systems background processes (servers) + provide information for clients (such as a GUI or command line). Multiple clients can communicate with a + single server process over the network. + + Component + A component in IBEX is, essentially, a mini-configuration. It can be used to create a configuration for a subset + of devices attached to an instrument. When the component is included in a configuration, the configuration "inherits" + all the definitions from the component. + + Configuration + A configuration defines the blocks, IOCs, macros and other items needed to control the instrument. + More specifically, a configuration is an information structure which defines and describes an instrument to IBEX. + + DAE (Data Acquisition Electronics) + The DAE is a set of electronic cards housed in a VXI/VME crate located in the instrument cabin/pod and maintained by ISIS electronics group. The DAE contains two types of card: + + - Detector cards (many): these cards record neutron counts + - Environment/period card (only one): this card distributes timing signals etc. and maintains global counters (e.g. number of ISIS pulses, proton charge delivered (PPP)) + + EPICS + `EPICS `_ is an open-source software framework for creating distributed control systems (i.e. for controlling devices which may be distributed across a network). EPICS is the underlying framework used to create IBEX. + + GENIE Python + GENIE Python is a python library for instrument control and scripting, maintained by the IBEX team. There is + training provided + + ICP (Instrument Control Program) + The ICP (sometimes called the ISIS ICP) is a server element of the IBEX control system that controls communication with the DAE. The ICP is also responsible for writing the RAW experiment data file at the end of a run or experiment. + + IOC (Input/Output Controller) + An IOC is an EPICS process that provides some service, often managing a device. + For example, access to a Eurotherm temperature controller is controlled via an IOC process that provides + Process Variable for the relevant control elements + + OPI (Operator Interface) + An OPI is a user interface element of IBEX. In essence, an OPI is a control panel for an individual device attached to an instrument. It allows you to view and modify the PVs that define the state of the device. For example, an OPI is displayed when you click on a device icon on a synoptic view. + + PV (Process Variable) + A Process Variable, usually referred to as a PV, is a named piece of information in the EPICS system, such as a + temperature setpoint or readback. PVs typically have structured names that uniquely identify them on the network. + An example of such a name, in this case for a motor, is: ``IN:LARMOR:MOT:MTR0101`` + + Server + A Server is a program or device that provides functionality to other devices. + + Synoptic + A Synoptic is a view in IBEX that allows users to visualize a beamline, including hardware components and PVs. diff --git a/doc/How-To.md b/doc/How-To.md new file mode 100644 index 0000000..ffdcd13 --- /dev/null +++ b/doc/How-To.md @@ -0,0 +1,13 @@ +# How do I ...? + +In this section of the IBEX User Manual, we describe how to do the most common and important tasks. + +We regularly run training sessions on IBEX. The slides from this course can be found {download}`here `. + +```{toctree} +:maxdepth: 1 +:titlesonly: +:glob: + +how_to/* +``` \ No newline at end of file diff --git a/doc/IBEX-File-Paths-page.rst b/doc/IBEX-File-Paths-page.rst new file mode 100644 index 0000000..b19a093 --- /dev/null +++ b/doc/IBEX-File-Paths-page.rst @@ -0,0 +1,32 @@ +Where is ...? +############# + +The installation of IBEX is common for most instruments you shouldn't need to delve into the paths as a user but as an instrument scientist there may be some items you wish to edit or look at. The system is set out as follows: + +* IBEX Client: ``C:\Instrument\Apps\Client_E4\ibex-client.exe`` there should be a shortcut on the task bar + +* IBEX Server: ``C:\Instrument\Apps\EPICS`` to start and stop the server; see :doc:`introduction/Starting-and-Stopping-IBEX`. + +* genie_python: ``C:\Instrument\Apps\Python3\genie_python.bat`` usually python is accessed through the client scripting console + +* Configurations: ``C:\Instrument\Settings\config\\configurations`` this directory contains configuration, components and IOC specific configuration. The IOC specific configurations include: + + - Galil: ``galil`` Galil motor configurations for all controllers, including jaws, axes and motion setpoint commands but not value + - motion setpoints: ``motionSetPoints`` the motion setpoints + - refl: ``refl\config.py`` default reflectometry configuration + - DAE tables: ``tables`` contains wiring, spectra and detector tables for the DAE + - TCB files: ``tcb`` contains the TCB files + +* Common calibration files: ``C:\Instrument\Settings\config\common`` calibration files for instruments e.g. Eurotherm sensors + +* Log files: These are in various places depending on the source see :external+ibex_developers_manual:doc:`iocs/troubleshooting/Log-file-location` on the developer's manual. + +* User scripts: instrument dependent often in ``c:\scripts`` + +* Instrument scripts: ``C:\Instrument\Settings\config\\Python`` version controlled instrument scripts which are accessed through ``inst.``. Either as a single file called ``inst.py`` or a folder called ``inst`` + +* Shared instrument scripts: ``C:\Instrument\scripts`` these are scripts shared between multiple instruments `see shared instrument scripts `_ + +* Data: ``C:\data`` the data recorded by the instrument + + diff --git a/doc/IBEX-GUI-Features.rst b/doc/IBEX-GUI-Features.rst new file mode 100644 index 0000000..0ac2f8c --- /dev/null +++ b/doc/IBEX-GUI-Features.rst @@ -0,0 +1,16 @@ +IBEX GUI +######## + +.. image:: ibex_client_large.png + +This section summarises the main features of IBEX as presented by the IBEX GUI client. + +You might find it helpful to refer to the schematic view below of the IBEX UI while reading this section. + +.. image:: IBEX_E4_schematic.png + +.. toctree:: + :maxdepth: 1 + :glob: + + gui/* diff --git a/doc/IBEX_E4_schematic.png b/doc/IBEX_E4_schematic.png new file mode 100644 index 0000000..427f51c Binary files /dev/null and b/doc/IBEX_E4_schematic.png differ diff --git a/doc/Instrument-Specific-Guidance.md b/doc/Instrument-Specific-Guidance.md new file mode 100644 index 0000000..b495074 --- /dev/null +++ b/doc/Instrument-Specific-Guidance.md @@ -0,0 +1,11 @@ +# Instrument-specific guidance + +Owing to the highly varied nature of the instruments that IBEX supports, some instruments have specific guidance for particular operations. + +```{toctree} +:maxdepth: 1 +:titlesonly: +:glob: + +inst_specific/* +``` \ No newline at end of file diff --git a/doc/Introduction.md b/doc/Introduction.md new file mode 100644 index 0000000..fe57631 --- /dev/null +++ b/doc/Introduction.md @@ -0,0 +1,10 @@ +# Introduction + +```{toctree} +:caption: Introduction +:maxdepth: 1 + +introduction/What-Is-IBEX +introduction/Installing-IBEX +introduction/Starting-and-Stopping-IBEX +``` diff --git a/doc/Key-Concepts-in-IBEX.rst b/doc/Key-Concepts-in-IBEX.rst new file mode 100644 index 0000000..fdd381f --- /dev/null +++ b/doc/Key-Concepts-in-IBEX.rst @@ -0,0 +1,196 @@ +Concepts +######## + +It is worth taking a few moments to appreciate some of the key concepts behind IBEX. + +.. contents:: **Contents** + +.. _concept_client_server: + +Clients & Servers +----------------- + +A client-server system is one that employs a distributed application architecture. In a client-server system, the workload is partitioned between the providers of information or services (i.e. servers) and requesters or consumers of information or services (i.e. clients). Clients request information or the use of a resource or service from server hosts. Each server host runs server programs which share information or resources with clients when requested to do so. Typically, the server and client run on separate computers connected via a network, but the client and server can also run as separate processes on the same computer. + +The design of IBEX follows this model: IBEX consists of a server component, which runs on the Instrument control PC, and a client component, which runs on a separate PC (but can also run on the instrument control PC, if necessary). IBEX has been created using the `EPICS `_ framework for creating distributed control systems. + +All Instruments should be installed in a consistent manner, these are detailed in :doc:`the 'Where is ...?' guide`. + +.. _concept_client: + +IBEX Client +~~~~~~~~~~~ + +The IBEX Client is a single application, which functions as a GUI for IBEX. + +.. _concept_genie: + +genie_python +~~~~~~~~~~~~ + +genie_python can also be thought of as a client of IBEX server. It operates as a scripting client, requesting information from the IBEX server and sending requests to change the state of devices attached to the instrument control PC. + +.. _ibex_server: + +IBEX Server +~~~~~~~~~~~ + +The IBEX server is not a single component, but a collection of components, which together control the individual devices which comprise a neutron or muon Instrument. The primary components of the IBEX server are: + +BlockServer + The core component of the IBEX server. The BlockServer provides the service that translates :doc:`/concepts/Process-Variables` into :doc:`/concepts/Blocks`. It also supports run-control and serves configuration information. + +ICP + The ICP (Instrument Control Program) is the process which controls the `DAE (Data Acquisition Electronics)`_. The ICP tells the DAE when to start and stop collecting data from the instrument detectors. The ICP is also responsible for combining the detector data with logged sample environment data and for transferring the final dataset to a data file. + +Archiver + The Archiver, as its name suggests, archives the values of process variables to a database. This service supports strip-chart plots of blocks & process variables and can also be used to inspect the history of process variables for diagnostic purposes. + +IOCs + IOCs (Input/Output Controllers) are processes which control individual devices attached to the instrument control PC. IOCs are analogous to LabVIEW VIs. IOCs communicate with other processes (e.g. the BlockServer or other IOCs) via :doc:`/concepts/Process-Variables`. Typically, there is one IOC for each device attached to the instrument control PC. + +Message Server + The Message Server intercepts console messages written by IOCs and stores them in a database. It also serves the messages to the IBEX client, so that the message log can be inspected and searched from the GUI. + +:doc:`Script Server` + The Script Server runs Python scripts submitted by authorised clients. After these scripts are run, the output is sent back to the IBEX client. The output of these scripts can be viewed inside the Script Server View. + +MySQL + MySQL is an open-source relational database system, which provides database services to + the Archiver and the Message Server. + +.. _concept_security: + +Security +~~~~~~~~ + +A critical aspect of any control system is security: in particular, who has control of an instrument at any point in time. By control, we mean the ability to change PVs or start/stop the collection of data. The security model in IBEX reflects current working practices at ISIS. + +.. _concept_subnet: + +Instrument Sub-Network +^^^^^^^^^^^^^^^^^^^^^^ + +Each instrument controlled by IBEX has its own sub-network. The sub-network is a self-contained, mini-network which connects the instrument blockhouse, the instrument machine room (which houses the instrument control PC and DAE rack) and the instrument cabin/pod. Each instrument sub-network is independent of the sub-network belonging to any other instrument. The instrument sub-network is connected to the wider ISIS network using a gateway. Also, the instrument control PC runs a process called the EPICS Gateway, which controls access to PVs on the instrument sub-network. + +This arrangement means that the devices attached to the instrument control PC are isolated from events elsewhere on the network. For example, should there be a need to shut down a part of the ISIS network (e.g. for maintenance reasons), the instrument sub-network will continue to run without interruption. Many hardware devices are not designed to be connected directly to busy, general purpose networks; by employing a sub-network, we can insulate these devices from the background traffic that exists on the rest of the network. A sub-network arrangement helps to make the instrument more resilient. + +.. _concept_control_permission: + +Who has Control? +^^^^^^^^^^^^^^^^ + +In IBEX, typically only PCs directly connected to the instrument sub-network can control the instrument. To control an instrument, your PC must be connected to a network port in the instrument cabin/pod, the instrument machine room or the instrument blockhouse. + +Any request from a PC for access to a PV is checked by the EPICS Gateway. If the request originates from within the instrument sub-network, the EPICS Gateway will allow full (read and write) access to the PV. If the request originates from outside the instrument sub-network, the EPICS Gateway will allow read-only access to the PV. Therefore, if your PC is not directly connected to the instrument sub-network, you can only view the status of an instrument. + +.. _concept_view_permission: + +Who can View an Instrument? +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Anyone on the ISIS network can view an instrument. For example: + +* another scientist, using another instrument, can use IBEX to view what is happening on your instrument. This is especially useful when instruments share infrastructure (e.g. the muon beamlines). +* an instrument scientist can use IBEX to view what is happening on your instrument from his or her office. +* a technician can use IBEX to view the status of a device. +* a support person can use IBEX to check what is happening on your instrument and help you troubleshoot problems. + +.. _concept_blocks_pvs: + +Blocks & Process Variables +-------------------------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + concepts/Blocks + concepts/Process-Variables + concepts/PV-Naming-Conventions + +.. _concept_dae: + +DAE (Data Acquisition Electronics) +---------------------------------- + +The DAE is a collection of electronic cards housed in a VXI/VME crate, which is located in the instrument cabin or pod. The DAE is maintained by the ISIS electronics group. There are two types of card in the DAE: + +Detector Cards + The DAE contains many detector cards, which are connected to the instrument detectors, and record neutron counts. + +Environment/Period Card + The DAE contains a single environment/period card, which distributes timing signals etc. and maintains global + counters (e.g. number of ISIS pulses, proton charge delivered (PPP)) + +The DAE is usually connected to the instrument control PC via a USB or MXI-2 cable. + +Settings for the DAE can be read and changed either through the :doc:`IBEX client ` or commands :doc:`issued in scripts `. + +What does the DAE do? +~~~~~~~~~~~~~~~~~~~~~ +The DAE: + +* Records the arrival time of neutrons at detectors relative to the ISIS pulse +* Histograms the neutron counts based on their time of arrival into “bins” chosen by scientists +* If desired, groups (gangs) detectors together +* If necessary, rejects (vetoes) data based on pre-defined criteria +* Saves all of this in “detector card memory” to be later read by the PC + +.. _concept_good_raw_frames: + +GOOD Frames and RAW Frames +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The DAE will only record data if it receives a “start pulse” signal. + +RAW Frame + A RAW Frame means the DAE received a “start pulse” signal, but data may or may not have been saved to the detector card. + +GOOD Frame + A GOOD Frame is a RAW frame where data was histogrammed and written to the detector card. + +RAW frames that do not become GOOD frames are called VETOED frames + +.. _concept_veto: + +Vetoes +~~~~~~ +A veto is a hardware signal that can, on a frame by frame basis, tell the DAE not to collect data. + +* The DAE supports four user-defined external vetoes (labelled VT0 -> VT3 on a crate), which can be connected to choppers, moderator, etc. +* Internal (FIFO) veto – triggered if too many counts in a single frame on any card +* SMP veto – triggered if chopper timing signal out of phase with ISIS +* Fermi chopper veto: checks for the arrival of a chopper signal within a given window on inelastic chopper spectrometers + + * Used on MERLIN, MAPS, MARI. On LET handled by chopper crate and so just an external veto. + +* ISIS 50Hz veto: vetoes frames when accelerator not running at 50Hz (e.g. during beam run up or diagnostics) + + * Used on IRIS/OSIRIS, but they also use ISISFREQ SECI block + +.. _concept_timing: + +DAE Timing Sources +~~~~~~~~~~~~~~~~~~ +The DAE can use one of three timing sources: + +* ISIS: uses the ISIS accelerator pulse from the cable plugged into the TOF socket +* SMP: uses the “secondary master pulse”, usually a chopper plugged into the SMP socket +* First TS1: uses the first ISIS pulse after the missing TS2 pulse (so 10Hz on TS1). +* Internal Test Clock: 50Hz timing signal provided internally by DAE + + * Used for quiet counts out of a cycle + * Need to turn off SMP veto as test clock is not synchronised to anything + +TS1, 50Hz running +^^^^^^^^^^^^^^^^^ +* Can choose either ISIS or SMP – however, they differ in what happens if beam goes off +* ISIS: beam off -> no signal and so no RAW frame +* SMP: if chopper continues to run -> RAW frame, which will be vetoed by the SMP veto as + there is no corresponding ISIS TOF pulse. + +TS1, 25Hz running +^^^^^^^^^^^^^^^^^ +* Must choose SMP (chopper) timing as this signal is the one at 25Hz +* If beam off, chopper continues to run -> RAW frame, but vetoed by SMP veto as no corresponding ISIS pulse +* Dashboard beam current calculated from DAE pulses, so 25Hz -> half ISIS beam current \ No newline at end of file diff --git a/doc/Obsolete.md b/doc/Obsolete.md new file mode 100644 index 0000000..a0de4fd --- /dev/null +++ b/doc/Obsolete.md @@ -0,0 +1,16 @@ +# Obsolete information + +:::{warning} +The guides in this section are obsolete and no longer relevant, for example because they document +migrations which have already happened on all instruments. + +The information in these documents is unlikely to be useful, except for historical context. +::: + +```{toctree} +:maxdepth: 1 +:titlesonly: +:glob: + +obsolete/* +``` \ No newline at end of file diff --git a/doc/Script-Generator.md b/doc/Script-Generator.md new file mode 100644 index 0000000..ae4bf2b --- /dev/null +++ b/doc/Script-Generator.md @@ -0,0 +1,17 @@ +# Script Generator + +```{toctree} +:caption: Introduction +:maxdepth: 1 +:glob: + +script_generator/* +``` + +If you are writing script definitions please check out [Writing Script Definitions](script_generator/Writing-Script-Definitions). + +If you are using predefined script definitions to generate scripts please check out [Using the Script Generator](script_generator/Using-the-Script-Generator) + +If you are having issues see [Troubleshooting the Script Generator](script_generator/Troubleshooting-the-Script-Generator) + +If you would like the script generator to load script definitions from or generate scripts to different areas please check out [Script Generator Customisation](script_generator/Script-Generator-Customisation) \ No newline at end of file diff --git a/doc/Scripting.md b/doc/Scripting.md new file mode 100644 index 0000000..88a6963 --- /dev/null +++ b/doc/Scripting.md @@ -0,0 +1,22 @@ +# Scripting + +There are two ways of running scripts in IBEX - locally, and on the IBEX server. + +Scripting in IBEX is done using python, with the `genie_python` library. The {external+genie_python:py:mod}`genie_python ` reference documentation gives a full account of what functions are available. + +This page is intended to give a broad guide to scripting for the +beginner and novice user. For a more in-depth discussion, see our [genie_python and IBEX training course](scripting/training_course/genie_python-and-IBEX-(Introduction)). + +```{toctree} +:caption: Introduction +:maxdepth: 1 +:glob: + +scripting/* +``` + +There is some specific [scripting advice for the Muon Front End](/inst_specific/Guidance-on-Writing-Scripts-for-the-Muon-Front-End) + +If you are new to Python, the Mantid team has created an excellent {external+mantid:ref}`Introduction to Python ` on the Mantid website. + +See also the {external+genie_python:py:mod}`genie` reference documentation. diff --git a/doc/The-Web-Dashboard.md b/doc/The-Web-Dashboard.md new file mode 100644 index 0000000..23caa95 --- /dev/null +++ b/doc/The-Web-Dashboard.md @@ -0,0 +1,25 @@ +# Web Dashboard + +The web dashboard (or data web) is a basic webpage that will give you information about the state of your instrument. + +It can be found at http://dataweb.isis.rl.ac.uk/ + +The view is read only and gives you a dashboard in a similar style to the desktop GUI as well as general instrument data and information on blocks. There is a checkbox at the bottom of the screen to show/hide hidden blocks. + +If you do not wish to have the title/users visible on this page you can set this via the desktop GUI in the DAE perspective -> Run Summary. + +## Block Value History + +The block names displayed should be links to a block history display plot - if they are not, you probably just need to clear your browser cached images and files. Access to the block history requires a username and password: +* For ISIS staff, enter your federal ID username (or stfc email address), and password +* For ISIS Users, you should enter your ISIS user office login details. In addition, you need to have created a visit (even if you are not coming to site) at https://users.facilities.rl.ac.uk/visits covering the dates that your experiment is in progress. + +For ISIS staff there is an enhanced plotting option available via the [Grafana Dashboard](web_dashboard/Grafana-Dashboard) + +```{toctree} +:hidden: +:titlesonly: +:maxdepth: 1 + +web_dashboard/Grafana-Dashboard +``` \ No newline at end of file diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css new file mode 100644 index 0000000..a759883 --- /dev/null +++ b/doc/_static/css/custom.css @@ -0,0 +1,23 @@ +.wy-table-responsive table td, .wy-table-responsive table th { + white-space: inherit; +} + +.wy-menu-vertical p.caption { + color: #70f10e; +} +.wy-nav-content { + max-width: 1000px !important; +} + +@keyframes highlight { + 0% { + background: #e3fccf; + } + 100% { + background: none; + } +} + +:target { + animation: highlight 5s; +} diff --git a/doc/_static/eclipse_4_changes.ppt b/doc/_static/eclipse_4_changes.ppt new file mode 100644 index 0000000..79dcc69 Binary files /dev/null and b/doc/_static/eclipse_4_changes.ppt differ diff --git a/doc/concepts/Blocks.rst b/doc/concepts/Blocks.rst new file mode 100644 index 0000000..a288a65 --- /dev/null +++ b/doc/concepts/Blocks.rst @@ -0,0 +1,66 @@ +Blocks +###### + +The IBEX concept of a block is similar to SECI, in that it is a relevant piece of information chosen by the scientist that will be displayed on the instrument dashboard and, if required, can be logged into the datafile. + +In IBEX, a block is, to all intents and purposes, an alias to a process variable. For example, the block ``Chop1Freq`` on LARMOR is defined to be the process variable ``IN:LARMOR:CS:SB:Chop1Freq``. It is much simpler to refer to a block than to refer to a process variable. Utilities like genie_python know about blocks, and you can use commands such as ``cset`` to access ``Chop1Freq``. However, you can access blocks using the name ``IN:LARMOR:CS:SB:Chop1Freq`` with any standard EPICS tool. + +Process variables are defined in more detail on the :doc:`/concepts/Process-Variables` page. + +Alarms +====== + +An IBEX block may be in alarm as well as having a value. Alarms signify potential problems with the data + +Disconnected +------------- + +A disconnected status implies that the user interface cannot access the variable which has been requested. + +Examples: + +* The relevant IOC is not running - for example, the relevant ioc is not listed in the current configuration +* The IOC is running on another computer, and there is no network availability + +These alarms appear with either a purple border or a solid purple background in the user interface. + +Invalid alarm +------------- + +An invalid alarm signifies that there was a problem acquiring this piece of data. Data marked with an invalid alarm should generally not be trusted. + +Examples: + +* The hardware has become unplugged or switched off +* The hardware replied in an unexpected way +* A setpoint has not been set (it will remain in an undefined state until set) + +These alarms appear with a purple border in the user interface. + +Major alarm +----------- + +A major alarm signifies that there is a serious problem with the data being reported by a device. Data marked with an major alarm may require attention from an equipment expert. + +Examples: + +* A fault status is being reported by the hardware +* A chopper is not in the correct operation mode + +*Note: it is possible to set your own limits on a value going into major alarm - please ask the IBEX team if you would like help setting this up* + +These alarms appear with a red border in the user interface. + +Minor alarm +----------- + +A minor alarm signifies a warning with the data being reported by a device. Data marked with a minor alarm should be checked, but if you are confident that the data is correct and within the expected ranges, can be ignored. + +Examples: + +* Motor parked on a limit switch +* Helium level in a cryostat falling low + +*Note: it is possible to set your own limits on a value going into minor alarm - please ask the IBEX team if you would like help setting this up* + +These alarms appear with an orange border in the user interface. diff --git a/doc/concepts/PV-Naming-Conventions.rst b/doc/concepts/PV-Naming-Conventions.rst new file mode 100644 index 0000000..94ab4f0 --- /dev/null +++ b/doc/concepts/PV-Naming-Conventions.rst @@ -0,0 +1,97 @@ +PV Naming Conventions +##################### + +Facilities running `EPICS `_ usually adopt a convention for naming PVs (:doc:`Process-Variables`). ISIS is no exception. + +The purpose of the naming convention is to: + +a. Provide a systematic means of describing the PV, +b. Ensure that the name of the PV is unique (within the facility). + +ISIS Naming Convention +---------------------- + +At ISIS, PV names are chosen to describe a function, not hardware/technology - the PV name is the purpose of a channel and is abstracted from the underlying hardware; the name of the IOC (to which the PV belongs) can, however, reflect technology/hardware/implementation. + +The essential format of the ISIS naming convention is ``DOMAIN:SUBDOMAIN:TECHNICALAREA:DEVICE:SUBDEVICE:SIGNAL`` + +PV names should contain only the following characters ``A-Z``, ``0-9``, ``_``, ``:``, ``*``. Notice that lowercase characters are not allowed. The colon character ``:`` is used to separate different elements of the PV name; therefore, do not use the ``:`` for other purposes (e.g. as part of an IOC name). To break up individual components of a PV name into readable segments, use the underscore, ``_`` character. + +In addition, PV names must start with a letter and must not end with ``_``. + +Domain & Subdomain Names +~~~~~~~~~~~~~~~~~~~~~~~~ + +Names appearing in the domain & subdomain levels include: + ++------+--------------------------------------------------------------------------------------------------------+ +| Name | Description | ++======+========================================================================================================+ +| AC | ISIS Accelerator/synchrotron related parameter | ++------+--------------------------------------------------------------------------------------------------------+ +| TG | ISIS Target related parameter | ++------+--------------------------------------------------------------------------------------------------------+ +| IN | Instrument related parameter | ++------+--------------------------------------------------------------------------------------------------------+ +| BL | Beamline – used if multiple instruments are sharing a common set of equipment; e.g, the muon beamlines | ++------+--------------------------------------------------------------------------------------------------------+ +| TE | Testing domain, used by local EPICS developers | ++------+--------------------------------------------------------------------------------------------------------+ + +In the instrument domain, the sub-domain is the full instrument name. For example: ``IN:GEM`` or ``IN:POLREF``. + +Technical Area and Device Names +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Technical Area and Device Names reflect the nature of the device that owns the PV in question. For example: + +* ``IN:GEM:MOT`` relates to PVs associated with motion control equipment on GEM. +* ``IN:ZOOM:VAC`` relates to PVs associated with vacuum equipment on ZOOM +* ``IN:IRIS:DAE`` relates to PVs associated with the DAE on IRIS +* ``IN:IMAT:MOT:MTRccmm`` relates to EPICS motor records on IMAT for a motor on controller number cc, motor number mm. These numbers are zero padded to two digits and start from 1 (e.g. MTR0101 is the first motor on the first controller). +* ``IN:LARMOR:MOT:JAWSmm`` mm-th set of jaws on LARMOR (e.g. JAWS01 is the first set of jaws, etc.). + +Signal Names +~~~~~~~~~~~~ + +Standard signal names include: + ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| Signal Name | Meaning | Valid Units | ++=============+=========================+==============================================================================================+ +| POS | Position | M, mm, cm | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| STAT | Status, State | Open, Closed, On, Off, Ok, Error | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| CURR | Current | A, mA, uA | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| VOLT | Voltage | kV, V | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| CMD | Device command | e.g. write to this to perform an action, such as start/stop a run | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| SEL | Select mode or position | | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| TEMP | Temperature | K | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| COUNT | Counter value | neutron counts | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| COUNTD | Counter value | as a distribution, i.e. divided by bin width - so neutron counts per microsecond for example | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| P, I, D | P, I, D values | e.g. on a Eurotherm | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| TOF | Time of flight | | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| TIME | An absolute timestamp | preferably in ISO8601 format | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ +| FIELD | Magnetic field | | ++-------------+-------------------------+----------------------------------------------------------------------------------------------+ + +If a value can fluctuate, these refer to the current measured value of a quantity and the signal qualifiers SP and RBV are used to indicate the desired value software requested (setpoint) and the desired value being used in the hardware (RBV) + +For example, for a TEMP signal + +* ``...:HEATER:TEMP`` Current temperature +* ``...:HEATER:TEMP:SP`` Temperature set point (requested value) – this is the value that was input in software and sent to the equipment. Writing to this PV will cause the setpoint to change +* ``...:HEATER:TEMP:SP:RBV`` This is the setpoint “readback” from hardware, which may differ from SP sent above if, for example, the hardware was unable to exactly match the requested value. By definition, a readback PV is read-only. Also if the SP was changed by some other mechanism (e.g. manually on the hardware) ``:SP`` would not reflect this, but ``:SP:RBV`` would. + +**Note:** The RBV suffix can be used more generally e.g. For P,I,D values you could have ``...:P`` and ``...:P:RBV`` diff --git a/doc/concepts/Process-Variables.rst b/doc/concepts/Process-Variables.rst new file mode 100644 index 0000000..24c19b2 --- /dev/null +++ b/doc/concepts/Process-Variables.rst @@ -0,0 +1,31 @@ +Process Variables +################# + +A key concept in EPICS, and hence IBEX, is the process variable. +In the underlying `EPICS `_ framework, a process variable (usually abbreviated to PV) is a named piece of information that can be read/monitored/changed. Information from hardware devices and elsewhere is exposed as process variables, and devices are controlled by writing to the appropriate process variables. + +Naming +------ + +A process variable name is simply a string of alpha-numeric characters. However, PV names are usually structured to conform to a naming convention, so that individual PV names are unique. The colon ":" character is used to separate the different sections of a PV name. At ISIS we use the following convention: + +* For an instrument all process variables relevant to that instrument will start with the ``IN:`` prefix, +* followed by the instrument name, +* followed by the device specific details (usually device name and variable name). + +For example + +* ``IN:LARMOR:DAE:GOODUAH`` is the PV that holds the good microamps on LARMOR +* ``IN:IMAT:DAE:GOODUAH`` is the PV that holds the good microamps on IMAT +* ``IN:LARMOR:MK3CHOPPER_01:CH1:FREQ`` is the PV that holds the frequency of the Mk3 Chopper on LARMOR + +Not all PVs belong to an instrument. Items not part of an instrument have a different prefix. For example, the accelerator generates values with a top-level prefix of ``AC:`` such as + +* ``AC:TS1:BEAM:CURR`` is the PV that holds the TS1 beam current + +Displaying +---------- +You can read a PV outside of IBEX by starting an EPICS terminal and running: + +| ``caget IN:LARMOR:DAE:GOODUAH`` +| ``camonitor IN:LARMOR:DAE:GOODUAH`` diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..e848a53 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,95 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + + +project = "IBEX User Manual" +copyright = "" +author = "ISIS Experiment Controls" +release = "0.1" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +nitpicky = True + +myst_enable_extensions = [ + "dollarmath", + "strikethrough", + "colon_fence", + "linkify", + "html_image", + "attrs_block", +] +suppress_warnings = ["myst.strikethrough", "myst.header"] + +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", + # and making summary tables at the top of API docs + "sphinx.ext.autosummary", + # This can parse google style docstrings + "sphinx.ext.napoleon", + # For linking to external sphinx documentation + "sphinx.ext.intersphinx", + # Add links to source code in API docs + "sphinx.ext.viewcode", + # Redirects + "sphinx_reredirects", + # Mermaid diagrams + "sphinxcontrib.mermaid", +] +mermaid_d3_zoom = True +napoleon_google_docstring = True +napoleon_numpy_docstring = False + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_context = { + "display_github": True, # Integrate GitHub + "github_user": "ISISComputingGroup", # Username + "github_repo": "ibex_user_manual", # Repo name + "github_version": "master", # Version + "conf_py_path": "/doc/", # Path in the checkout to the docs root +} + +html_title = "IBEX User Manual" +html_short_title = "User Manual" +html_theme = "sphinx_rtd_theme" +html_logo = "logo.svg" +html_theme_options = { + "logo_only": False, + "style_nav_header_background": "#343131", +} +html_favicon = "favicon.ico" +html_static_path = ["_static"] +html_css_files = [ + "css/custom.css", +] + +autoclass_content = "both" +myst_heading_anchors = 7 +myst_linkify_fuzzy_links = False +html_last_updated_fmt = "" +html_show_copyright = False + +spelling_lang = "en_GB" +spelling_filters = ["enchant.tokenize.MentionFilter"] +spelling_warning = True +spelling_show_suggestions = True +spelling_suggestion_limit = 3 + +intersphinx_mapping = { + "ibex_developers_manual": ("https://isiscomputinggroup.github.io/ibex_developers_manual/", None), + "mantid": ("https://docs.mantidproject.org/", None), + "genie_python": ("https://isiscomputinggroup.github.io/genie", None), + "matplotlib": ("https://matplotlib.org", None), +} diff --git a/doc/device_specific/Eurotherm.rst b/doc/device_specific/Eurotherm.rst new file mode 100644 index 0000000..5a01148 --- /dev/null +++ b/doc/device_specific/Eurotherm.rst @@ -0,0 +1,52 @@ +Eurotherm +######### + +The Eurotherm is usually used to measure and control temperature; however it has also been used to measure pressures. It measures the resistance of an external sensor. + +.. contents:: **Contents** + +Calibration +----------- + +The two measurement modes in which the Eurotherm is used are: + +#. Measuring a temperature directly: use the ``None.txt`` calibration file + +#. Measuring a resistance and then using a calibration file to convert to a temperature: In which case use the calibration file which is correct for your sensor. The calibration files are in ``C:\Instrument\Settings\config\common\temp_sensors`` + +The calibration file is set using the `File` box in the `Sensor Calibration` area on the Eurotherm OPI. + +Ramping +------- + +The Eurotherm can be made to ramp slowly through a temperature gradient. It achieves this by updating the set point every 5s to create the desired ramp rate; It does not check that the Eurotherm can respond quickly enough. To set it into ramping mode: + +#. Set the `Ramp rate` (N.B. The units of this are K/min) +#. Set `Ramp` to be on + +When the Eurotherm is ramping the ramping light will be lit. + +PID LookUp +---------- + +The PID and maximum heater settings can be set dependent on the setpoint temperature. To do this switch the lookup on using the button on the OPI; the light will illuminate. + +The values for the settings are stored in a file in ``C:\Instrument\Settings\config\common\ramps``: + +#. The ramp file is a space separated file of values for set point temperature, P, I, D and heater (see the example file for the format) +#. The file *must* be in set point temperature order small to large +#. The set points are the lowest temperature at which the values should be used. +#. Any set point lower than the first entry will use the first entry. + +For example if your file was:: + + SP P I D Heater + 100 10 11 12 13 + 200 20 21 22 23 + 300 30 31 32 33 + +Then a setpoint of: + +- 220 would use `20 21 22 23` +- 300 would use `300 30 31 32 33` +- 10 would use `100 10 11 12 13` diff --git a/doc/device_specific/FZJ-Fermi-Chopper.rst b/doc/device_specific/FZJ-Fermi-Chopper.rst new file mode 100644 index 0000000..08d339b --- /dev/null +++ b/doc/device_specific/FZJ-Fermi-Chopper.rst @@ -0,0 +1,174 @@ +FZJ Fermi chopper (used on MERLIN, MAPS, MARI) +############################################## + +The FZJ Fermi Chopper has a relatively complex IOC due to its somewhat idiosyncratic communications behaviour. The following things are non-standard: + +- Custom checksum algorithm in stream device. This is specific to this style of Fermi chopper. +- ``aSub`` record to parse a response string from the hardware. +- ``aSub`` record to decide how to send the speed setpoint to the device +- ``aSub`` record to decide whether a given command is allowed to be sent +- ``SNL`` state machine to ensure that setpoints and their readbacks stay in sync (for both gate width and phase delay) +- There is logic in the DB records to prevent sending a speed setpoint that is equal to the current speed setpoint readback. +- There is (equipment) safety logic in the IOC. For more details see below. + +Settings +---------- + +Depending on which specific Fermi chopper system is being used, there are slight variations in the communications protocol of the choppers. The expected settings are: + +========== ===================== ============= ================================================================ +Beamline ``INST`` macro ``MHZ`` macro Drive parameters +========== ===================== ============= ================================================================ +MERLIN merlin 50.4 "MERLIN small parameters" or "MERLIN large parameters" (see Note 1) +MARI merlin (see Note 2) 50.4 "MERLIN large parameters" (See Note 3) +MAPS maps 18.0 *The controller on MAPS does not support changing parameters* +========== ===================== ============= ================================================================ + + +**Note 1:** I believe this choice depends on which physical rotor is installed into the chopper + +**Note 2:** The controller on MARI is identical to MERLIN's from a communications perspective - hence re-using MERLIN's communications code. + +**Note 3:** I believe the "HET/MARI" parameters refer to a very old version of the hardware, before the chopper was upgraded to be more like MERLIN's. Chopper group may be able to give a more definitive answer. + +Diagnostic logs +----------------- +The logs for the Fermi chopper are kept in ``C:\Instrument\var\logs\ioc\FERMCHOP_01-``. These logs contain the following information: + +- All commands that are used to start the driver. Whenever the driver first starts, there will be a large block of ``epicsEnvSet`` commands. The startup process is finished when an ``epics>`` prompt comes up in the log (there will be lots of commands in between - these can be ignored) +- Communication conditions and problems, for example unexpected replies from the chopper. These messages may include parts of the raw (hexadecimal) response from the chopper. +- Information about the chopper state (e.g. interlock statuses, temperatures out of range) **when they transition between valid/invalid states**. These messages are prefixed with ``Chopper status:`` +- Information about actions that the driver is taking to ensure the settings stay correct. There is a state machine that detects when the chopper forgets it's settings and resends the correct settings. These messages are prefixed with ``Keep SP and RBV in sync``. +- Messages regarding whether certain commands were accepted by the driver. These messages are prefixed with ``commandCheck``. The driver will reject commands (and print a message in the log) if: + + * The user attempts to spin up the chopper with the bearings off + * The user attempts to resend a "spin-up" command while the chopper is set and spinning at 600Hz. This is a mitigation for the 600Hz issue experienced on MERLIN, details further down this page. + * The user attempts to switch off the magnetic bearings while the actual chopper speed is >10Hz. + * When the driver sends a command successfully, it will also print a message in the log with the numeric command that it has send. The translation for these numeric commands is: + + * 1: Switch drive on/stop mode + * 2: Switch drive off + * 3: Switch drive on/run mode + * 4: Switch magnetic bearings on + * 5: Switch magnetic bearings off + * 6: Use MERLIN large chopper parameters + * 7: Use MARI chopper parameters + * 8: Use MERLIN small chopper parameters + +Unexpected Delay / Speed / Gate Width settings +------------------------------------------------ + +**Delay: high and low byte ordering** + +The delay setpoint can be wrong if the high byte and low byte of the setpoint are received in the wrong order. The observed behaviour in this state is that the setpoint readback will appear to be correct, but the actual delay will home in on a different (incorrect) value. Resending the delay setpoint in the correct order fixes this state. + +This problem has been solved by defining the order of the packets in the stream device protocol, including an appropriate wait between them. For more details, see issue #2628. + +**Gate width setpoint readback is wrong** + +Occasionally the device will get confused and reset its gate width to a semi-random value. Resending the gate width causes it to pick up the correct value again. This problem is mitigated in the driver by having a state machine which keeps the gate width and gate width readback in sync. + +**Set commands are ignored** + +Sometimes the chopper crate simply ignores a setpoint which was sent. Unfortunately the crate does not respond to a set command so we can't tell if there was a comms error. This problem is mitigated in the driver by having state machines which keep the setpoints and their readbacks in sync for gate width, phase delay and chopper speed. + +Additionally, the chopper speed is now put under run control as part of MERLIN's ``set_ei`` script to make it more obvious if the chopper speed isn't in the expected range. + +**600Hz issue [Specific to MERLIN]** + +At 600Hz, the chopper exhibits strange behaviour: +- If the speed setpoint is already 600Hz and a speed setpoint of 600Hz is resent, the chopper gets confused. The phase delay will appear to be zero forever. To get out of this state, you need to send a different setpoint, wait for the actual device speed to drop (e.g. to 599Hz), and then 600Hz can be set successfully. This problem is mitigated in the driver by not sending a speed setpoint which is equal to the current speed setpoint readback. + +- If the device is at 600Hz and already spinning, sending the "switch drive on and run" command causes the same bug as above. This problem is mitigated in the driver by disallowing the "switch drive on and run" command from being sent if the chopper speed is >595Hz and the setpoint readback is 600Hz and the drive generator is already on. + +For more details, see issue #2741. + +Won't phase correctly / delay is fluctuating +-------------------------------------------- + +**Synchrotron off** + +The phase delay of the chopper is a delay between the synchrotron pulse and the the chopper being in a specific position. If the synchrotron is not running the delay will appear to fluctuate wildly as there is no reference synchrotron pulse. This should rectify itself without intervention and the chopper will re-phase once the synchrotron timing pulse comes back online. + +**Won't phase correctly (unknown causes)** + +Occasionally the chopper will get into a state where it can't phase correctly. The symptom is that the phase readback fluctuates wildly and never settles on the phase setpoint. We are unsure of the root cause. Sending the chopper to a different speed setpoint and then back to the original setpoint seems to let the chopper phase correctly. + +When plotting the phase using the instrument archive, you may see a "beating" pattern like below. Here the amplitude of the oscillation is ~30us, a typical phase window would be ~10us so this will result in the DAE vetoing a percentage of frames based on the chopper being "out of phase" at that time. As noted in issue #4764 the ``set_ei`` method on MERLIN will attempt to correct for this. + +Drive turns off unexpectedly +---------------------------- + +There are a variety of hardware & software conditions that can cause the chopper to spin down. + +**Hardware / firmware conditions** +Firstly, check in the "advanced" tab of the OPI - any of the following will cause the device to spin down: + +- Interlock open (the scientists know how to reset this) + + * Note, the interlock only has to report "open" for a moment for the chopper to spin down. If the vacuum gauge is faulty, it may trip the interlock momentarily, which will cause the chopper to spin down but when subsequently looking at the OPI the interlock will appear OK. If this is the case then contact the chopper group as this is a hardware fault and is not something we can compensate for in software. +- Electronics or motor temperatures too hot (not sure where the firmware limit is - may be 50C according to manual but this is not clear) +- A few other (less common) conditions indicated by red interlock LEDs on the OPI + +**Software conditions** +There are (equipment) safety checks in the IOC which will cause the IOC to request a spin down. Hitting any of these conditions will cause a message to be logged containing the words ``this will cause the chopper to spin down`` - this can be searched for in the log file if it is believed that the IBEX driver has caused the chopper to spin down. + +- If the electronics temperatures or motor temperatures go above 45 Celsius. + + * **Electronics overheats occur somewhat frequently on MERLIN, especially during hot weather.** + * Need to wait for create to cool sufficiently and then spin the chopper back up as normal. + * Instrument scientists aware of this and know how to reset it. + +- If the auto zero voltages are out of range (absolute value higher than 3 volts) +- If the actual chopper speed is above 606Hz +- If the magnetic bearing is off while the chopper is at speed + +Crate does not respond / Crate responds infrequently +---------------------------------------------------- + +**VISA vs Asyn serial [Specific to Maps]** +An issue was seen when first commissioning the MAPS Fermi under EPICS. Symptoms were very odd: + +- Cannot communicate using VISA nor Asyn under EPICS +- If chopper crate and instrument PC are power cycled, may need to run LabVIEW driver once before epics can talk. We are still not sure why this is. +- If EPICS+Visa is subsequently run, it will upset the comms and will need to run the LabVIEW to "clear" the error + +**Shortened status command [Specific to Maps]** +On MAPS, the crate's communications layer can fail, causing the device to ignore the standard polling command (``#0000000$``). To recover from this state, send the shortened command ``0$`` repeatedly until you get a response. The IOC should automatically do this whenever it detects no response to the standard command. + +Chopper refuses to spin up +---------------------------- +**IOC command logic** + +There is logic in the IOC to prevent sending commands which would put the chopper into a disallowed state. For example, it is not permitted to send "switch drive on and run" if the magnetic bearings are off. Check the IOC log - there should be entries saying either "...sending command to device..." or "...refusing to send command to device...". + +**Bearings need power cycling** + +First CAREFULLY check that the chopper is stopped. The chopper will be damaged if bearings get turned off while it is spinning. Then hit "turn drive off and stop" in IBEX, wait a few seconds, delevitate the chopper by switching off the magnetic bearings, wait a few seconds, turn the bearings on again, wait a few seconds, and hit "switch drive on and run". + +Chopper veto stuck on +--------------------- + +**Veto cable not properly plugged in** + +Ask DAE experts to unplug and re-plug in the veto cable. + +**Chopper phase fluctuating causing intermittent veto** + +If you are getting a fluctuating Fermi chopper veto, e.g. it is vetoing 50% of frames, it may be because the phase is fluctuating in and out of range. See section above about delay fluctuating for possible resolutions. + +Chopper run control settings incorrect +--------------------------------------- + +**Configurations have been reloaded** + +The ``set_ei`` script (at least on MERLIN) puts the chopper under run control. If a config is reloaded then these settings will be lost. To recover, simply re-run ``set_ei``. + +Chopper speed stuck between 1-49Hz +---------------------------------- + +**Broken speed sensor** + +The symptom is that the chopper will be stuck at a specific speed, e.g. ``28 Hz`` indefinitely when attempting to spin down, or for a few minutes (until it physically passes the relevant speed) when spinning up. The choppers cannot be commanded by IBEX to run at speeds that are not multiples of 50Hz. This will also cause the chopper lift to be inoperative (as the chopper lift still believes the chopper is spinning and therefore inhibits motion). + +The actual speed shown on the front panel of the chopper is shown in ``rpm``, but IBEX works in ``Hz``, therefore you can compare the two by multiplying/dividing by 60. If the front panel of the chopper also shows the same issue with a stuck speed, then it is likely a mechanical problem - e.g. a broken speed sensor - consult with the chopper team. \ No newline at end of file diff --git a/doc/device_specific/Kepco-Power-Supply.md b/doc/device_specific/Kepco-Power-Supply.md new file mode 100644 index 0000000..6563002 --- /dev/null +++ b/doc/device_specific/Kepco-Power-Supply.md @@ -0,0 +1,30 @@ +# KEPCO Power Supply + +KEPCO power supply units (PSU) come in various sizes and models. The two major differences are analogue (i.e. the PSU has analogue dials on the front panel) and digital (i.e. the PSU has digital readbacks on the front panel). + +KEPCO PSUs run in two modes: + +1. Voltage Mode + - Setting voltage means the KEPCO will supply will try to maintain the requested (+ve or -ve) voltage + - In voltage mode, the current that is set will be the maximum allowed current. I.e. If the resistance is low then to reach the desired voltage a current larger than the setpoint will be needed, so the KEPCO will not reach the desired voltage. +1. Current Mode + - Setting a current will mean the KEPCO will supply the given current. + - In current mode, the voltage that is set will be the maximum allowed current. + +## Macros + +`RESET_ON_START` This macro controls whether the ioc resets and resends parameters on start of the IOC and can be set to 0, 1 or 2. + +- 0 tells the IOC to not reset and resend setpoints on startup +- 1 tells the IOC to reset and resend setpoints if the firmware is less than version 2.0 +- 2 tells the IOC to reset and resend setpoints no matter what the firmware version is + +## Troubleshooting + +### Current/voltage will not go negative when I set the current/voltage + +If the device is in voltage mode then the sign of the current will be set by the voltage, not the current and vice-versa. + +### Current/voltage does not reach the value set + +For voltage mode, check the current setting is high enough (see voltage mode above). In current mode, check that the voltage is set high enough (see current mode above). diff --git a/doc/device_specific/Lakeshore-340.md b/doc/device_specific/Lakeshore-340.md new file mode 100644 index 0000000..9c2b0e1 --- /dev/null +++ b/doc/device_specific/Lakeshore-340.md @@ -0,0 +1,17 @@ +# Lakeshore 340 + +Guide on Lakeshore 340 excitation thresholds. + +To use a file set the configuration macros of the IOC to be `USE_EXCITATION_THRESHOLD_FILE` to be YES and `EXCITATION_THRESHOLD_FILE` to your file name e.g. `Parameters.txt`. + +They are loaded from the instrument config area for example on MUSR `Instrument\Settings\config\NDXMUSR\configurations\excitation_thresholds`. They are `.txt` files where each line is a pair of temperature threshold and excitation value in that order separated by a comma, for example: + +``` +20,30 nA +15,1 mV +18,100 nA +``` + +The file is read from top to bottom and the first temperature threshold that is greater than the temperature setpoint on the Lakeshore 340 is the line that is selected. Subsequently, the IOC will wait for the temperature to reach the setpoint and then set the excitation to the value on the same file line as the matching temperature threshold. If no temperature threshold is found to match the file then the last excitation listed in the file will be set. + +If the set file contains invalid values or does not exist then the OPI will display this on the excitations tab. \ No newline at end of file diff --git a/doc/favicon.ico b/doc/favicon.ico new file mode 100644 index 0000000..8ec971a Binary files /dev/null and b/doc/favicon.ico differ diff --git a/doc/genie_python_and_ibex.pptx b/doc/genie_python_and_ibex.pptx new file mode 100644 index 0000000..019225b Binary files /dev/null and b/doc/genie_python_and_ibex.pptx differ diff --git a/doc/gui/Banner.rst b/doc/gui/Banner.rst new file mode 100644 index 0000000..e6d5a6d --- /dev/null +++ b/doc/gui/Banner.rst @@ -0,0 +1,10 @@ +Banner +###### + +The Banner is located at the bottom of the IBEX GUI window. + +The Banner displays information about the current status of the IBEX GUI. For instance, it displays the name of the current configuration. + +The Banner also displays important status information about selected devices on an instrument. It is customisable on an instrument by instrument basis. For example, on LARMOR, the Banner is customised to display a message indicating whether any motors are moving and to display a message if the bump strip has been tripped. On IMAT, the Banner is customised to display the current position of the beam attenuator device. + +Please discuss how you would like the Banner to be customised for your instrument with the Experiment Controls team. \ No newline at end of file diff --git a/doc/gui/Blocks-and-Groups.rst b/doc/gui/Blocks-and-Groups.rst new file mode 100644 index 0000000..8cc57c0 --- /dev/null +++ b/doc/gui/Blocks-and-Groups.rst @@ -0,0 +1,47 @@ +Blocks & Groups +############### + +The blocks & groups area of the IBEX GUI is situated to the right of the :doc:`Dashboard`. It displays all the blocks defined for the currently loaded instrument configuration. The blocks are arranged in groups. + +.. contents:: **Contents** + +Blocks +------ +A block is, in effect, an alias for a process variable. Process variables are defined in more detail on the :doc:`/concepts/Process-Variables` page. Any process variable can be assigned to a block. Blocks are defined in more detail on the :doc:`/concepts/Blocks` page. + +Run Control Indicators +~~~~~~~~~~~~~~~~~~~~~~ + +A tick mark or an X mark next to a block indicates that the block is under run control. + +* An unadorned block (i.e. no symbol next to the value of the block) means the block is not under run control. +* An icon featuring a black check mark on a green background next to the value means the block is under run control and within its limits. +* An icon featuring a white X on a red background next to the value means that the block is under run control and outside its limits. + +Alarm State Indicators +~~~~~~~~~~~~~~~~~~~~~~ + +A coloured box surrounding the block indicates that the block is in an alarm state (or, more correctly, that the underlying PV is in an alarm state). + +* No border means the block is connected and is not in an alarm state. +* An orange border around the block value means the block is under minor alarm. +* A red border around the block value means the block is under major alarm. +* A purple border around the block value means the block is disconnected. + +If a block is in an alarm state, you should check the Alarms View to find out why an alarm has been raised. + +If a block is flagged as being disconnected, it typically means there is a problem with the device which provides the value of the block or with the IOC which controls the device: + +#. the IOC is not running. +#. the IOC has not been correctly configured and, therefore, is not communicating correctly with the device. +#. the device is not connected to the instrument control PC (e.g. a cable is disconnected). +#. the device is switched off. +#. there is a fault with the device. + +The last of these possibilities is the least likely to occur. It is good practice to rule out the other possibilities before concluding that there is a fault with the device. + +Groups +------ +Blocks can be arranged in groups. This provides a convenient way to group related blocks. You can create as many groups as you need to categorise your blocks. + +If you do not explicitly assign a block to a group, it will, by default, be assigned to a group called "Other". diff --git a/doc/gui/Dashboard.rst b/doc/gui/Dashboard.rst new file mode 100644 index 0000000..8113206 --- /dev/null +++ b/doc/gui/Dashboard.rst @@ -0,0 +1,53 @@ +Dashboard +######### + +The dashboard occupies the top left-hand corner of the IBEX GUI. It provides a brief summary of the current status of the instrument. + +The top part of the dashboard shows the name of the instrument to which the IBEX GUI is connected and the current state of the instrument, along with the current Run number and the state of the instrument shutter. + +The bottom part of the dashboard summarises the current experiment title and users. At the lower left, the dashboard displays information on good frames vs raw frames, the beam current and monitor counts. At the lower right, the dashboard displays the current instrument time, the length of the current run and the period. + +Additional notes +~~~~~~~~~~~~~~~~~ + +- The instrument time is the date/time measured by the clock on the instrument control PC. It might not be the same as the time displayed on your PC or other electronic devices (e.g. your phone). +- The users displayed include PIs and users, but not contacts + +Dashboard States & Colours +-------------------------- + +The meanings of the dashboard states and colours are: + ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| State | Background Colour | Meaning | ++============+===================+============================================================================================+ +| RUNNING | LIGHT_GREEN | DAE is collecting data | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| SETUP | LIGHT_BLUE | DAE is read to begin a run | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| PAUSED | RED | DAE has been paused by a script or user | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| WAITING | DARK_YELLOW | DAE is not collecting data and is waiting for a run controlled variable to come into range | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| VETOING | DARK_YELLOW | A veto is active and data is not collected | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| ENDING | BLUE | A run is has been ended and the data is being written (it will change to setup when done). | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| PAUSING | DARK_RED | DAE is about to be in the paused state | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| BEGINNING | GREEN | DAE is starting a run | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| ABORTING | BLUE | DAE run is being aborted | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| RESUMING | GREEN | DAE is resuming after being paused | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| PROCESSING | YELLOW | DAE is setting up | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| UPDATING | YELLOW | | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| STORING | YELLOW | | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| SAVING | YELLOW | | ++------------+-------------------+--------------------------------------------------------------------------------------------+ +| UNKNOWN | YELLOW | | ++------------+-------------------+--------------------------------------------------------------------------------------------+ diff --git a/doc/gui/Experiment-Details.rst b/doc/gui/Experiment-Details.rst new file mode 100644 index 0000000..d91c00a --- /dev/null +++ b/doc/gui/Experiment-Details.rst @@ -0,0 +1,28 @@ +Experiment Details +################## + +The experiment details view gives you the ability to input meta data about your experiment, such as RB number, experiment team and sample/beamline parameters. + +.. contents:: **Contents** + +RB Number +--------- +.. image:: RBNumber.PNG + +If you know the RB number of your experiment you can input it here. Once you press the Set button IBEX will automatically update the experiment team with the appropriate users if the run has been previously scheduled. **The RB number for Xpress runs should also be put in here but you will have to add users for it manually** + +If you don't know your RB number (and the experiment has been scheduled) clicking the search button will open a dialog box where you can search for your name: + +.. image:: RBNameSearch.PNG + +Experiment Team +--------------- +.. image:: ExperimentTeams.PNG + +Here you can see, and edit, the details of everyone involved in your experiment. By clicking on any of the text in the table you can modify it. You can also use the following buttons to make changes: + +- Add: Add a new member to the team +- Remove: Remove the selected team member +- Clear: Clear the whole list +- Set: Set any changes that you've made. (You should immediately see the users update in the dashboard) + \ No newline at end of file diff --git a/doc/gui/ExperimentTeams.PNG b/doc/gui/ExperimentTeams.PNG new file mode 100644 index 0000000..2233e22 Binary files /dev/null and b/doc/gui/ExperimentTeams.PNG differ diff --git a/doc/gui/Menu-Bar.rst b/doc/gui/Menu-Bar.rst new file mode 100644 index 0000000..80390d2 --- /dev/null +++ b/doc/gui/Menu-Bar.rst @@ -0,0 +1,104 @@ +Menu Bar +######## + +The menu bar on the IBEX GUI provides access to the application features described below. + +.. contents:: **Contents** + +IBEX Menu +--------- +Switch Instrument + Select the Switch Instrument menu item to re-direct the IBEX GUI to view a different instrument. + + **Please Note:** If you connect to an instrument from outside the instrument's sub-network (i.e. if you are not in the instrument blockhouse or cabin/pod), you will only be able to view the instrument (i.e. you will not be able to make changes to any of the fields). + +Manager Mode + Selecting the Manager Mode option allows the user to enter manager mode after entering the manager password. + +Exit IBEX Client + Select the Exit IBEX Client menu item to quit. Please note, quitting the IBEX Client does not terminate the IBEX server, which will continue to run on the instrument control PC. + +Configuration Menu +------------------ +Edit Current Configuration + Select the Edit Current Configuration menu item to make changes to the currently loaded instrument configuration. +Configurations + Select the Configuration menu item to perform one of the following actions: + + * New - create a new configuration + * Load - replace the current configuration with a different configuration loaded from a file + * Edit - edit an existing configuration (independently of the current configuration) + * Delete - delete a configuration + * Recent - load one of the last 5 loaded configurations + +Components + Select the Components menu item to perform one of the following actions: + + * New - create a new component + * Import - import a component from another instrument + * Edit - edit an existing component + * Delete - delete a component + + +Synoptic Menu +------------- +New + Create a new synoptic. +Edit + Select an existing synoptic and edit it. +Delete + Select an existing synoptic to delete it. + +IOC Menu +-------- +Start/stop IOCs + Selecting the Start/stop IOCs menu item displays a dialog allowing you to start an IOC or to stop an IOC that is currently running. + +Run-Control Menu +---------------- +View run-control settings + Selecting the View Run-Control Settings menu item displays a dialog showing you which blocks (if any) are currently under run-control. You can also assign new run-control settings to blocks and modify or remove existing run-control settings. + +You can change run-control settings in 3 different ways (2 temporary and 1 permanent changes) + +* Temporary change + 1. You can set temporary run-controls settings via Run-Control menu. + Input low and high limit from the bottom of the window. + + 2. You can also set temporary run-controls settings via scripting. + Type ``g.cget(b.YOUR_BLOCK_NAME, runstate=true, highlimit= x, lowlimit=y``, where x and y are numbers you want to set as limits. + + **Note:** Defaults can be restored using the ``Restore Configuration Values`` for the selected block or ``Restore All Configuration Values`` + buttons. + + Temporary setting will override the default set for the block in the configuration and will persist until the configuration is reloaded. + + +* Permanent change + You can set default run-controls settings that will remain, unless you change it temporarily. + + 1. From ``Run-Control`` menu, select the block you would like to change and click ``Edit Host Configuration`` to change the settings. + +The :doc:`Blocks-and-Groups` page describes how blocks under run-control are shown in the GUI. + +Preferences Menu +---------------- + +Colour settings + Allows the user to one of the supported colour schemes: + + * Standard colour scheme + * Alternative colour scheme 1 + +Help Menu +--------- +About + Selecting the "About" menu item displays a dialog showing the current version of the IBEX client and the current version of the IBEX server (running on the instrument control PC to which you are currently connected). If you need to report a problem with IBEX, support staff may ask you to look up this information, so that they know which version of the IBEX software you are using. +User manual + Selecting the "User manual" menu item opens the IBEX user manual in a web browser. +Console Log + The console log is used by support staff to help them diagnose any problems that IBEX might encounter. +Icon Licences + View the licences for the icons used in IBEX +Get help + Displays support telephone numbers and how to get help or report problems. \ No newline at end of file diff --git a/doc/gui/RBNameSearch.PNG b/doc/gui/RBNameSearch.PNG new file mode 100644 index 0000000..14a7f36 Binary files /dev/null and b/doc/gui/RBNameSearch.PNG differ diff --git a/doc/gui/RBNumber.PNG b/doc/gui/RBNumber.PNG new file mode 100644 index 0000000..63e8256 Binary files /dev/null and b/doc/gui/RBNumber.PNG differ diff --git a/doc/gui/Reflectometry-View.rst b/doc/gui/Reflectometry-View.rst new file mode 100644 index 0000000..9e36c2f --- /dev/null +++ b/doc/gui/Reflectometry-View.rst @@ -0,0 +1,224 @@ +Reflectometry View +################## + +.. contents:: **Contents** + +The reflectometry view combines all the components needing to run most experiments for a reflectometer in one place; it is only available on reflectometers and replaces the scripting view. Below is an example of this view from POLREF. + +.. image:: reflectometry/FullScreen.png + +This screen is split into 3 main areas shown in this schematic rendering. + +.. image:: reflectometry/FullScreenSchematic.png + +- **Scripting Window**: This is a python console which allow you to issue commands to the reflectometry IOC. These commands range in complexity from getting the value of a parameter to a full alignment. + +- **Plotting Window**: This shows plots created using matplotlib. Matplotlib is a python plotting library that can be used from the scripting window; The `scan` command will draw it plots to here too. + +- **Reflectometry Window**: This is the main view of the reflectometer. It displays where the reflectometer is and allow you to set where it should move to. This view consists of multiple tabs and the next sections will explain their uses and introduce the conventions that are used. + +Conventions +=========== + +Parameters +---------- + +Most screens show lists of parameters. Each of those parameters has a similar form, for example: + +1. Real number parameter + +.. image:: reflectometry/Parameter.png + +2. IN Out of beam parameter + +.. image:: reflectometry/ParameterInOut.png + +3. Real number parameter with a characteristic value + +.. image:: reflectometry/ParameterCharacteristic.png + +Each parameter has multiple bits and these are (starting on the left): + +- Letters: Indicate some information about the parameter. `M` means that the parameter is in the current mode (see Operation Mode below) +- Label (in bold): The name of the parameter. Usually the same as the block name. +- RBV Value: The readback, this is the current position of the reflectometer; usually this is relative to the beam. +- SP:RBV Value: The setpoint readback, this where the reflectometer will move to when the move all button is pressed or when another parameter's move button is pressed and this parameter is in the mode. If the setpoint is set then it would move to that value instead. +- SP Box/Button/Drop Down: The setpoint, this is the value that the motor will move to if the parameter move button is pressed or the move all button is pressed. +- Move button: The parameters move button, when pressed it will cause the parameter's setpoint to be applied and the reflectometer to move to the new position. If it is in the mode then all other parameters in the mode will also be set. +- Characteristic Value (Optional): This is a value which is a characteristic value you might want to consider when reading the parameter. Often this is the motor position which most represents the parameter. + +Parameter States +---------------- + +**Moving** + +.. image:: reflectometry/ParameterMoving.png + +Readback value (RBV) has a green background: an underlying motor for the parameter is moving + +**Changed/Set** + +.. image:: reflectometry/ParameterChanged.png + +Set point (SP) has a yellow background: the setpoint has been changed but not yet applied to the reflectometer. It will be applied when either the move all button is pressed or the parameters move button is pressed + +**Component Out of the Beam** + +.. image:: reflectometry/ParameterDisabled.png + +Individual parameter move button is replaced with an "Out" label. This indicates that the component for the axis this parameter controls is currently parked out of beam. You can still enter set points but they will not be applied to the axis until the component is moved back into the beam. + +**Set-point mirrors Readback** + +.. image:: reflectometry/Parameter_sp_mirrors_rbv.png + +This parameter is setup so that the setpoint mirrors the readback value, on every move the setpoint gets set to the current readback value. This is useful for an axis that can affect position calculations but cannot be actively moved by the reflectometry server. The readback setpoint (`RBV:SP`) can be different to the readback value (`RBV`) because it is only set when the parameter is moved to, i.e. the underlying motor has moved since last beamline move. + +**Not in Position** + +.. image:: reflectometry/ParameterNotInPosition.png + +Whole parameter area has a single red border: this shows that the movement has stopped but that the setpoint and readback do not agree. This could be because the tolerance is too tight (motors can only achieve a certain accuracy) but more likely is that a motor has not stopped at the right place. Check the positions and if necessary repeat the movement. This should be reported to an Instrument scientist as it may indicate a future problem. + +**Minor Alarm** + +.. image:: reflectometry/ParameterMinor.png + +Readback (RBV) has an orange border (tool tip include the word MINOR): there is a minor error with the parameter, check the value looks sensible. This can be that the underlying motor has hit a limit switch and stopped, which is expected for some parameters. + +**Major Alarm** + +.. image:: reflectometry/ParameterMajor.png + +Readback (RBV) has an red border (tool tip include the word MAJOR): there is a major error with the parameter. Stop using it until you find out what is wrong. + +**Invalid** + +.. image:: reflectometry/ParameterInvalid.png + +Readback (RBV) has an purple border (tool tip include the word INVALID): the parameter is invalid. This is usually because the underlying motor has stopped responding. Stop using the reflectometer and find out what has gone wrong + + +Reflectometry View Tabs +======================= + +Front Panel +----------- + +Each instrument has a unique front panel but they all have a similar layout. The schematic view shows the main areas of the panel. For peculiarities of instruments see the :external+ibex_developers_manual:doc:`instrument specific pages in the dev manual` + +.. image:: reflectometry/FrontPanelSchematic.png + +Vertical Slits / Horizontal Slits +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The vertical and horizontal slit sections allows the slits to be set in the various direction, the parameters are displayed and set as standard parameters. Note that: + +- Several instruments have a beam blocker mode. Beam blocker mode can be set using the drop down. In this mode the user controls the slit positions directly and not the gaps; to help with this the gaps are no longer displayed and the blades are displayed instead. + +- POLREF can have the sample horizontal or vertical, the slits controlling the collimation of the beam are always top left (i.e. vertical when the sample is horizontal and horizontal when the sample is vertical). + +Important Parameters +~~~~~~~~~~~~~~~~~~~~ + +The important parameters section contains parameters that control the overall beam path. For instance theta is normally top right (and on some instruments the label is slightly larger). This section may also contain super mirror angles, and whether the beam line is in laser mode. Laser mode is where components, e.g. the monitor are removed from the beam to allow the laser to travel through the system for alignment. + +Sample Stack +~~~~~~~~~~~~ + +These parameters control the position of the sample. In general the sample stack is not included in the mode so will not be automatically set when you change the rest of the parameters. E.g. if you change the super mirror angle the sample stack will not track the beam. Instead you must set the parameters or click the move button to make the sample stack move to its new position. The degrees of freedom depend on the beamline, some common degrees of freedom are: + +- Phi: angle in the same direction as theta, this is relative to the incoming beam to the sample and so should be the same as theta when you want to maintain the elastic scattering condition. +- Psi/Chi: rotate the sample in the planes other than theta for alignment. +- Height: Distance between the beam and the centre of rotation; usually set a 0. This moves the course z stage tracking the beam. +- Height2: Distance from the sample centre of rotation to the sample. This is used to align the sample with the beam. Some instruments do not have a height2 and so should use height for this purpose as well. +- Trans: Distance perpendicular to the beam for the sample + +Footprint Calculator +~~~~~~~~~~~~~~~~~~~~ + +The footprint calculator calculates the resolution and beam footprint given parameters about your sample. There are three calculation, one for the setpoint, one for setpoint RBV and one for the readback. + +Operation Mode +~~~~~~~~~~~~~~ + +The operation mode panel allows you to set the mode that beamline should run in. A mode consists of two part, initial value and a list of parameters that are in the mode. Initial values are the value for parameters, e.g. whether a components is in the beam or the values position of a slit. If the `apply mode inits on move` checkbox is checked then the initial values will be reapplied every time the beam line is moved. Which parameters are in the mode determines which parameters will be reapplied as the beam moves. So if a slit is in the mode as the beam moves its distance to the beam will be kept constant. Whereas if the slit is not in the mode it will not move its position unless a new set point is set or the move button is pressed. + +Common modes are: + +- NR: Neutron reflection, no super mirror just reflect from the sample +- PNR: Polarised neutron reflection, this mode uses a super mirror to reflect or polarise the beam +- DISABLED: In this mode the tracking is disabled, components move relative to their positions at the point the mode is selected (with the exception of theta which will still move the detector or bench). For instance, if you where at 0 theta and 0 supermirror angle and entered DISABLE mode then a move of supermirror angle would just change that angle, a change in a slit offset would still be relative to the 0 position not the current beam position. This mode is used during super mirror alignment and when the experiment is outside of the normal parameters for other modes. + +Server Status +~~~~~~~~~~~~~ + +The server status panel reports information, warnings and error that occur in the IOC. If there is a warning or error it should be taken seriously and the fault should be fixed before taking data. The status is cleared before each move. + +Known errors that can be ignored (and will be fixed in upcoming releases): + +- None + +Move All button +~~~~~~~~~~~~~~~ + +The move `all button` sets all currently changed parameters (in yellow) and moves the beamline to these positions. This is different from the smaller parameter move button which will set only the associated parameter. + +Apply move inits on mode +~~~~~~~~~~~~~~~~~~~~~~~~ + +When `Apply move inits on mode` is ticked and move all is pressed then all the initial values for the mode will be set before the move, this will override any you have set. The move will then commence normally to that position. This is usually the correct when running an experiment because the initial values set up most components to track the beam with an offset of 0. + +Motion Indicator +~~~~~~~~~~~~~~~~ + +The motion indicator is green when a motor is moving somewhere on the beamline. Currently it will also flicker if one of the motor encoders is changing between two values, this often happens when the motor stops between two values; we hope to fix this issue in the future. + +STOP ALL MOTION +~~~~~~~~~~~~~~~ + +Press the `STOP ALL MOTION` button if something is going wrong, it will stop all motors. + +Collimation Plane Parameters +---------------------------- + +Parameters on the collimation plane parameters tab are parameters which related to positions in the collimation plane. For example if the beam moves in the vertical plane these will be height offsets and phi/theta like angles. + +Activation Parameters +--------------------- + +Parameters on the activation parameters tab set whether components are active in the beam. For example whether the super mirror is in the beam or not. + +Slit Parameters +--------------- + +The slit parameters tab contains parameters that control the slit gaps and positions for both horizontal and vertical slits. + +Other Parameters +---------------- + +The other parameters tab displays parameter which are those not found on other tabs, they tend to control movement in the non collimation plan, e.g. translation of the sample. + +Driver Corrections +------------------ + +.. image:: reflectometry/DriverCorrections.png + +The driver correction tab displays the value of any engineering corrections that are currently being applied to the motors. :external+ibex_developers_manual:ref:`Engineering corrections are set in the configuration file` and allow the instrument scientist to correct the positions of components which do not follow the geometric calculation of the reflectometry IOC. This is one of the reasons why a motor position may be different from a geometric calculation of the beam. + +Constants +--------- + +.. image:: reflectometry/Constants.png + +The constants panel shows the constants for the current instrument and configuration and can be accessed in scripts if needed. These contains mostly positions of the components along the beamline. + +Error Log +--------- + +The error log tab shows a more detailed view of errors reported in the instrument status panel. + +Advanced +--------------- + +The advanced panel is for Instrument Scientists only. It allows them to more easily align the instrument. diff --git a/doc/gui/Script-Server.rst b/doc/gui/Script-Server.rst new file mode 100644 index 0000000..3467b43 --- /dev/null +++ b/doc/gui/Script-Server.rst @@ -0,0 +1,12 @@ +Script Server +############# + +.. image:: script-server.png + +IBEX features a script server, which allows you to write scripts and submit them to the server to run, which enables you to queue multiple scripts which the server will execute for you. Note that you can still use the :doc:`../Scripting` view to run your scripts. If you'd like us to disable either view button (script server or scripting) on your instrument, please let us know. + +To access the script server, click 'Script Server' on the view selector on the left-hand side (see :doc:`Views`). This view allows you to create and queue scripts, as well as show which script is currently running and which line the script server is currently executing. It also allows you to view and edit scripts in the queue by double clicking on them. + +You can write scripts within the Script Server view in IBEX or load a pre-written script from elsewhere on the system. You can also save scripts that you have written within IBEX. + +Do not use matplotlib commands in scripts which you send to the Script Server because matplotlib will spawn a plot window on the server and your script will pause until the plot window is closed. \ No newline at end of file diff --git a/doc/gui/Scripting-View.rst b/doc/gui/Scripting-View.rst new file mode 100644 index 0000000..7dc55e7 --- /dev/null +++ b/doc/gui/Scripting-View.rst @@ -0,0 +1,100 @@ +Scripting View +############## + +The Scripting-View displays a Python console, allowing you to load and execute Python or genie_python scripts. **Note**: Scripts running in the Scripting View are independent of scripts running on the Script Server and independent of scripts running in other consoles and clients. + +This window should be used for: + +- Quick functionality, e.g. set the jaws up for a number of runs +- Running visualisation and plotting routines +- Developing scripts. + +Experimental runs should, where possible, be run on the :doc:`script server` because these are independent of the client and only one script sever script can run at any one time (you can still run console scripts when the script server script is running). + +Multiple Consoles and Views +--------------------------- + +The IBEX Gui supports both multiple consoles and multiple views on those consoles. This is not as user-friendly as it could be but is inherited from an open source component that we use. You should think of this as multiple versions of genie_python, each running in a console, which you can view through one or many windows. To see how to utilise this read the following toolbar section. + +Tool Bar +-------- + +The tools bar at the top of every python console view looks like: + +.. image:: scripting_view_genie_python_tool_bar.png + +This has multiple functions, from left to right: + +- Stop genie_python console +- Save python console output +- Stop execution +- Clear the console +- Pin console: does nothing +- Change console being viewed in a console view +- New console (genie_python console or console view) + +**New genie_python console** + +To start a new genie_python click on the add console button: + +.. image:: scripting_view_new_console_button.png + +this will open a drop-down: + +.. image:: scripting_view_new_console_dropdown.png + +choose `PyDev console` which opens the pop-up: + +.. image:: scripting_view_new_console_popup.png + +Choose `Python console` from this pop-up and then OK. **Note:** At this point all open console views will switch to viewing the new console. + +**New console view** + +To create a new view on a console click on the add console button: + +.. image:: scripting_view_new_console_button.png + +this will open a drop-down: + +.. image:: scripting_view_new_console_dropdown.png + +choose `New Console View`. + +**Stop genie_python console** + +To stop a genie_python console click on the stop button (red left most square): + +.. image:: scripting_view_stop_button.png + +**Close Console View** + +All but the last view can be closed using the cross on the tab. + +.. image:: scripting_view_cross.png + +**Stop execution** + +Execution of python can be stopped by pressing ` + c` or clicking on the interrupt button (yellow right most square) + +.. image:: scripting_view_stop_execution.png + +**Change console being viewed in a console view** + +To select which console to view click on the console drop-down arrow (clicking on the icon cycles through consoles). + +.. image:: scripting_view_console_view_dropdown.png + +This will give you a list of active consoles running in this client. Select the one you wish to view. + +**Clear the console** + +A console can be cleared by clicking on clear console button: + +.. image:: scripting_view_console_clear.png + +**Save python console output** + +All the commands and outputs from a python console can be saved to a file using the save console view button: + +.. image:: scripting_view_console_view_save.png diff --git a/doc/gui/Views.rst b/doc/gui/Views.rst new file mode 100644 index 0000000..fbba12d --- /dev/null +++ b/doc/gui/Views.rst @@ -0,0 +1,125 @@ +Views +##### + +The main area of the IBEX GUI is reserved for displaying different types of view. Each displays a different aspect of the instrument. + +.. contents:: **Contents** + +Movable Panels +-------------- + +You can resize panels and move panels around inside of a view in IBEX. + +.. image:: ibex_client_windows_moved.png + :target: perspectives_moved_large.png + +If you want to return to the default panel arrangement within a view, click on the `Reset Layout`_ button in the top left-hand corner + +.. image:: reset_layout_button.png + +to reset the layout. + +**Note:** If you switch views then the layout is kept in the previous view. Each view will keep its panel layout until IBEX client is closed or the `Reset Layout`_ button is pressed. + +View Selector +------------- + +The View Selector, situated on the left-hand side of the IBEX GUI, is a column of buttons. Change a to a view by clicking on the associated button. The view button highlighted in blue indicates the currently selected view. + +Which views are visible to select is dependent on the settings which can be changed in: Main Toolbar -> Preferences -> Select visible perspectives + + +Views +------ + +Reset Layout +============= + +.. image:: reset_layout_button.png + +The Reset Layout View resets the layout of the windows back to their default position. If the layout has been changed, then this button becomes highlighted in red. + +.. _view_alarms: + +Alarms +============= +The Alarms View displays the alarm state of all devices attached to the instrument control PC. It will flash red if there are any alarms. Also, the number of alarms will appear in brackets on the button. If this view is selected and there are alarms, the button will stay highlighted in red if there are alarms. + +.. _view_beam_status: + +Beam Status +=========== +The Beam Status View displays the status of the synchrotron, TS1 and TS2 beams. It also displays MCR news. +To add/log a PV to the configuration, right-click to the text box next to the PV name. + +.. _view_dae: + +DAE +=== +The DAE View allows you to set up and control the DAE. See :doc:`/how_to/Manage-the-DAE` for further details. + +.. _view_device_screens: + +Device Screens +============== +The Device Screens view allows you to set up, control and view OPIs for different devices. + +.. _view_exp_details: + +Experiment Details +=================== +The Experiment Details View allows you to look up details of your current experiment using the RB number. See :doc:`Experiment-Details` for further details. + +.. _view_ioc_log: + +IOC Log +======= +The IOC Log View displays a log of all the messages sent by the IOCs which control the devices attached to the instrument control PC. + +.. _view_journal_viewer: + +Journal Viewer +============== +The Journal Viewer displays information about previous runs made on the instrument. + +.. _view_log_plotter: + +Log Plotter +=========== +The Log Plotter View allows you to plot a strip-chart graph of any block or process variable. See :doc:`/how_to/Plot-a-Block-Graph` for more details. If the buttons to add PVs to Log Plotter don't work, it is probably because Log Plotter perspective is disabled. It can be re-enabled from settings at the top bar. + +.. _view_motors: + +Motors +====== +The Motors View displays the status of all motors connected to the instrument control PC. You can also control all motors from this view. The Motors View is most useful for instruments with large numbers of motors. + +.. _view_reflectometry: + +Reflectometry +============= +The :doc:`Reflectometry-View` is available to reflectometers that combines all the components needing to run most experiments for a reflectometer in one place. Typically this view replaces the scripting view. + +.. _view_script_server: + +Script Server +============= +The Script Server View displays the current script being run, the queue of scripts to be run on the Script server and the output of any scripts. See :doc:`Script-Server` for more details. + +.. _view_scripting: + +Scripting +========= +Selecting the :doc:`Scripting-View` displays a Python console, allowing you to load and execute Python or genie_python scripts. **Note**: Scripts running in the Scripting View are independent of scripts running on the Script Server. + +.. _view_synoptic: + +Synoptic +======== +The Synoptic View provides a schematic overview of your instrument. It is a convenient way to navigate to any device attached to the instrument control PC. The :doc:`/how_to/Create-and-Manage-Synoptics` page provide more detail on how to create and manage synoptics. + +.. _view_web_links: + +Web Links +========= +The Web Links View is a collection of convenient web links. \ No newline at end of file diff --git a/doc/gui/ibex_client_windows_moved.png b/doc/gui/ibex_client_windows_moved.png new file mode 100644 index 0000000..9a59fd5 Binary files /dev/null and b/doc/gui/ibex_client_windows_moved.png differ diff --git a/doc/gui/reflectometry/Constants.png b/doc/gui/reflectometry/Constants.png new file mode 100644 index 0000000..6c5247f Binary files /dev/null and b/doc/gui/reflectometry/Constants.png differ diff --git a/doc/gui/reflectometry/DriverCorrections.png b/doc/gui/reflectometry/DriverCorrections.png new file mode 100644 index 0000000..f3a41b1 Binary files /dev/null and b/doc/gui/reflectometry/DriverCorrections.png differ diff --git a/doc/gui/reflectometry/FrontPanelSchematic.png b/doc/gui/reflectometry/FrontPanelSchematic.png new file mode 100644 index 0000000..3e66c40 Binary files /dev/null and b/doc/gui/reflectometry/FrontPanelSchematic.png differ diff --git a/doc/gui/reflectometry/FullScreen.png b/doc/gui/reflectometry/FullScreen.png new file mode 100644 index 0000000..7e261c8 Binary files /dev/null and b/doc/gui/reflectometry/FullScreen.png differ diff --git a/doc/gui/reflectometry/FullScreenSchematic.png b/doc/gui/reflectometry/FullScreenSchematic.png new file mode 100644 index 0000000..80ac2e2 Binary files /dev/null and b/doc/gui/reflectometry/FullScreenSchematic.png differ diff --git a/doc/gui/reflectometry/Parameter.png b/doc/gui/reflectometry/Parameter.png new file mode 100644 index 0000000..fe90e80 Binary files /dev/null and b/doc/gui/reflectometry/Parameter.png differ diff --git a/doc/gui/reflectometry/ParameterChanged.png b/doc/gui/reflectometry/ParameterChanged.png new file mode 100644 index 0000000..23f821d Binary files /dev/null and b/doc/gui/reflectometry/ParameterChanged.png differ diff --git a/doc/gui/reflectometry/ParameterCharacteristic.png b/doc/gui/reflectometry/ParameterCharacteristic.png new file mode 100644 index 0000000..416dd63 Binary files /dev/null and b/doc/gui/reflectometry/ParameterCharacteristic.png differ diff --git a/doc/gui/reflectometry/ParameterDisabled.png b/doc/gui/reflectometry/ParameterDisabled.png new file mode 100644 index 0000000..0bea4e7 Binary files /dev/null and b/doc/gui/reflectometry/ParameterDisabled.png differ diff --git a/doc/gui/reflectometry/ParameterInOut.png b/doc/gui/reflectometry/ParameterInOut.png new file mode 100644 index 0000000..5d44478 Binary files /dev/null and b/doc/gui/reflectometry/ParameterInOut.png differ diff --git a/doc/gui/reflectometry/ParameterInvalid.png b/doc/gui/reflectometry/ParameterInvalid.png new file mode 100644 index 0000000..45608d4 Binary files /dev/null and b/doc/gui/reflectometry/ParameterInvalid.png differ diff --git a/doc/gui/reflectometry/ParameterMajor.png b/doc/gui/reflectometry/ParameterMajor.png new file mode 100644 index 0000000..fa305dd Binary files /dev/null and b/doc/gui/reflectometry/ParameterMajor.png differ diff --git a/doc/gui/reflectometry/ParameterMinor.png b/doc/gui/reflectometry/ParameterMinor.png new file mode 100644 index 0000000..1c51232 Binary files /dev/null and b/doc/gui/reflectometry/ParameterMinor.png differ diff --git a/doc/gui/reflectometry/ParameterMoving.png b/doc/gui/reflectometry/ParameterMoving.png new file mode 100644 index 0000000..471a00a Binary files /dev/null and b/doc/gui/reflectometry/ParameterMoving.png differ diff --git a/doc/gui/reflectometry/ParameterNotInPosition.png b/doc/gui/reflectometry/ParameterNotInPosition.png new file mode 100644 index 0000000..8d18339 Binary files /dev/null and b/doc/gui/reflectometry/ParameterNotInPosition.png differ diff --git a/doc/gui/reflectometry/Parameter_sp_mirrors_rbv.png b/doc/gui/reflectometry/Parameter_sp_mirrors_rbv.png new file mode 100644 index 0000000..a1a7194 Binary files /dev/null and b/doc/gui/reflectometry/Parameter_sp_mirrors_rbv.png differ diff --git a/doc/gui/reflectometry/RedefineMotors.png b/doc/gui/reflectometry/RedefineMotors.png new file mode 100644 index 0000000..f13f0d2 Binary files /dev/null and b/doc/gui/reflectometry/RedefineMotors.png differ diff --git a/doc/gui/reset_layout_button.png b/doc/gui/reset_layout_button.png new file mode 100644 index 0000000..27a2923 Binary files /dev/null and b/doc/gui/reset_layout_button.png differ diff --git a/doc/gui/script-server.png b/doc/gui/script-server.png new file mode 100644 index 0000000..a27b594 Binary files /dev/null and b/doc/gui/script-server.png differ diff --git a/doc/gui/script_server_large.png b/doc/gui/script_server_large.png new file mode 100644 index 0000000..212a4b1 Binary files /dev/null and b/doc/gui/script_server_large.png differ diff --git a/doc/gui/scripting_view_console_clear.png b/doc/gui/scripting_view_console_clear.png new file mode 100644 index 0000000..e8b395e Binary files /dev/null and b/doc/gui/scripting_view_console_clear.png differ diff --git a/doc/gui/scripting_view_console_view_dropdown.png b/doc/gui/scripting_view_console_view_dropdown.png new file mode 100644 index 0000000..c8648bd Binary files /dev/null and b/doc/gui/scripting_view_console_view_dropdown.png differ diff --git a/doc/gui/scripting_view_console_view_save.png b/doc/gui/scripting_view_console_view_save.png new file mode 100644 index 0000000..34d9906 Binary files /dev/null and b/doc/gui/scripting_view_console_view_save.png differ diff --git a/doc/gui/scripting_view_cross.png b/doc/gui/scripting_view_cross.png new file mode 100644 index 0000000..37e5876 Binary files /dev/null and b/doc/gui/scripting_view_cross.png differ diff --git a/doc/gui/scripting_view_genie_python_tool_bar.png b/doc/gui/scripting_view_genie_python_tool_bar.png new file mode 100644 index 0000000..a176a6c Binary files /dev/null and b/doc/gui/scripting_view_genie_python_tool_bar.png differ diff --git a/doc/gui/scripting_view_new_console_button.png b/doc/gui/scripting_view_new_console_button.png new file mode 100644 index 0000000..abaed1d Binary files /dev/null and b/doc/gui/scripting_view_new_console_button.png differ diff --git a/doc/gui/scripting_view_new_console_dropdown.png b/doc/gui/scripting_view_new_console_dropdown.png new file mode 100644 index 0000000..ff1f4cb Binary files /dev/null and b/doc/gui/scripting_view_new_console_dropdown.png differ diff --git a/doc/gui/scripting_view_new_console_popup.png b/doc/gui/scripting_view_new_console_popup.png new file mode 100644 index 0000000..046e277 Binary files /dev/null and b/doc/gui/scripting_view_new_console_popup.png differ diff --git a/doc/gui/scripting_view_stop_button.png b/doc/gui/scripting_view_stop_button.png new file mode 100644 index 0000000..25b19f0 Binary files /dev/null and b/doc/gui/scripting_view_stop_button.png differ diff --git a/doc/gui/scripting_view_stop_execution.png b/doc/gui/scripting_view_stop_execution.png new file mode 100644 index 0000000..ddd22fa Binary files /dev/null and b/doc/gui/scripting_view_stop_execution.png differ diff --git a/doc/how_to/Add-blocks-to-run-title.md b/doc/how_to/Add-blocks-to-run-title.md new file mode 100644 index 0000000..0e21a7b --- /dev/null +++ b/doc/how_to/Add-blocks-to-run-title.md @@ -0,0 +1,18 @@ +# Add blocks to run title + +The value of a block can be embedded in a run title. This can be useful to differentiate the content of a run quickly at a glance. + +The syntax to add a block to a run name is `@BLOCKNAME@` in the run title. For example: +``` +Run with temperature @TEMPERATURE@ at angle @ANGLE@ +``` +where `TEMPERATURE` and `ANGLE` are the block names to be embedded. +If the temperature was 298 and angle 180, the run title would be saved as `Run with temperature 298 at angle 180`. + +This syntax can be used in both the IBEX GUI and through scripts. + +## Things to note + - The block **must** be logged. + - The block names are case sensitive, so capitalisation must be constant. + - The block value is updated in the title every time the block updates. Because of this, saving block values to the run title is best used when the values stay constant throughout the run. Otherwise the final value of the block will be saved in the title. + - Blocks looking at binary or enumeration (BI/MBBI) fields will be saved only as their integer representation. For example, if a block could be 'on' or 'off', the saved value would be 0 or 1 rather than its string. \ No newline at end of file diff --git a/doc/how_to/Create-and-Manage-Components.rst b/doc/how_to/Create-and-Manage-Components.rst new file mode 100644 index 0000000..4420fdc --- /dev/null +++ b/doc/how_to/Create-and-Manage-Components.rst @@ -0,0 +1,64 @@ +Create and Manage Components +############################ + +Many instrument configurations have a number of devices and settings in common. A component is a mini configuration (or sub-configuration) which provides a means of defining a selection of IOCs, Blocks, Groups, etc. that can be treated as a single object. Other configurations can then include the component which means that common IOCs, Block and other settings do not have to be repeatedly added to each configuration. It also means that changes need only be made to a single object - if a component is changed the changes will be inherited by all the configurations that use that component. + +One of the most common and useful ways to use a component is to create a "base" component. A "base" component defines a configuration for all the devices permanently attached to an instrument. Any new configuration can then include the "base" component and inherit all the IOCs, blocks, groups, macros, etc. associated with the permanent devices. + +Components are also frequently used to describe equipment (either a single device or a group of devices) that move between different instruments (e.g. a cryostat and associated temperature controllers). By defining a component to describe the equipment on the first instrument, the component can be copied across to the second instrument at the same time as the equipment is moved. This saves having to re-define all the relevant blocks, groups, etc. in a new configuration on the second instrument. + +.. contents:: **Contents** + +Create a Component +------------------ + +There are several ways to create a component: + +Save an existing Configuration as a Component + You can save an existing configuration as a component. When you click on the ``Save as...`` button on the Edit Configuration dialog (see :doc:`Create-and-Manage-Configurations`) the resulting Save As... dialog contains a check-box labelled ``Save the configuration as a component``. By default, this check-box is unchecked. Click on the ``Save the configuration as a component`` check-box and then click the ``OK`` button to save the configuration as a component. + + Once you have saved the configuration as a component, you can edit it as a component. + +Create a New Component + You can create a new component directly from the ``Configuration`` menu. Simply select ``Configurations > New`` from the ``Configuration`` menu. IBEX will then display the `New Configuration` dialog. + + The process of defining a component is essentially the same as the process of defining a configuration - the New Component dialog is identical to the New Configuration dialog. Refer to :doc:`Create-and-Manage-Configurations` for a full description of how to use the various tabs on the New Component dialog. + +Import a Component +------------------ + +To import a component: + +#. Select ``Components > Import`` from the ``Configuration`` menu. +#. IBEX displays the import component selection dialog, which lists all available instruments and their components. +#. Select an instrument you want to import a component from. +#. Select a component you want to import from that instrument and then press the ``Import`` button. +#. IBEX displays the Import Component dialog which is identical to the New Component dialog. Refer to :doc:`Create-and-Manage-Configurations` for a full description of how to use the various tabs on the Edit Component dialog (as described in `Create a Component`_). + +Before saving the imported component, please check the following: + * The communication settings for each IOC are correct. (COM port, IP address, etc.) + * Make sure that any remote IOCs (mobile devices not part of any beamline) in the imported component are needed and configured correctly. + * Check for any IOCs which may rely on autosave or settings area items. + * Check if the instrument prefix of non-local blocks is correct. + +**Note:** You will not be able to import a component from an instrument that is on a different version. + +Edit a Component +---------------- + +To edit a component: + +#. Select ``Components > Edit`` from the ``Configuration`` menu. +#. IBEX displays the Edit Component dialog which is identical to the New Component dialog. Refer to :doc:`Create-and-Manage-Configurations` for a full description of how to use the various tabs on the Edit Component dialog (as described in `Create a Component`_). + +Delete a Component +------------------ + +To delete a component: + +#. Select ``Components > Delete`` from the ``Configuration`` menu. +#. IBEX displays the Delete Component dialog, which lists all the components defined for your instrument. +#. Select a component from the list and press the ``OK`` button +#. IBEX deletes the selected component. + +**Note:** When you delete a component it really is deleted. It is no longer available to be used by IBEX. Before deleting a component, please be sure that you really do want to delete it. If you unintentionally delete a component, please contact the Experiment Controls team - it may be possible to recover the deleted component. \ No newline at end of file diff --git a/doc/how_to/Create-and-Manage-Configurations.rst b/doc/how_to/Create-and-Manage-Configurations.rst new file mode 100644 index 0000000..6ed21af --- /dev/null +++ b/doc/how_to/Create-and-Manage-Configurations.rst @@ -0,0 +1,327 @@ +Create and Manage Configurations +################################ + +A configuration is the means by which an instrument is described and defined to IBEX. A configuration defines the blocks, IOCs, components, macros and other items which IBEX needs to use to control the instrument. You can create multiple configurations for an instrument, to describe and define how the instrument has been set up for different experiments. In some cases, there are macro settings which are global for the instrument. These are set outside of the GUI and override the values in the configuration. These are setting which should not change, e.g. the IP address of the Galil motors (see the section below on how to alter these). + +**Please note:** An IBEX configuration is **not** the same as a Mantid configuration. IBEX and Mantid view instruments in fundamentally different ways, which means that their respective configurations are not interchangeable. + +.. contents:: **Contents** + +Creating a Configuration +------------------------ + +To create a configuration: + +#. Select ``Configurations > New`` from the ``Configuration`` menu. +#. IBEX displays the Edit Configuration dialog, which contains the following eight sections: + + #. Summary + #. Components + #. IOCs + #. Blocks + #. Groups + #. IOC Macros + #. IOC PV Values + #. IOC PV Sets + +#. At the bottom of the dialog are two buttons + +Save as... + Click on the ``Save as...`` button to save your changes. The Save as... dialog prompts you to provide a name and description for your configuration. + + * You must provide a name for the configuration. + * The name of the configuration can contain only the characters a-z, A-Z, 0-9 and _ (underscore). + * The name must also start with a character. + * The name of the configuration must be unique (on your instrument). + + The Save as... dialog also includes an option to save a configuration as a component. The :doc:`Create-and-Manage-Components` page describes more details about this option. + +Cancel + Click on the ``Cancel`` button to exit the Edit Configuration dialog without saving your changes. + +We'll describe each of the Edit Configuration dialog tabs in turn. + +Summary +~~~~~~~ + +The Summary allows you to create a short description for your configuration. It also allows you to associate a default synoptic view with your configuration. + +The summary is displayed at the top of the dialog and contains the following fields: + +Name + This is a read-only field. It is defined when you save the configuration. When you are creating a new configuration, the ``Name:`` field will be empty. + +Description + Provide a short description of your configuration. Configuration names can sometimes be a little cryptic; a brief description will help you to remember the purpose of the configuration better. + +Synoptic + IBEX allows you to create different synoptic views for use with different configurations. Therefore, it is convenient to associate a synoptic view with a configuration - it saves you from having to remember the association. Your chosen synoptic will be used as the default synoptic whenever you use this configuration. + +Protected + Selecting this checkbox will restrict editing of this configuration to users in "manager mode". Manager mode can be enabled under the IBEX menu, by inputting the password (please ask experiment controls group if you are unsure about the password) + +Dynamic + Mark this configuration or component as dynamic, meaning that it can be edited automatically in response to certain events. Note that this is advanced functionality which requires other IBEX components to be configured; please ask experiment controls group if you believe you need this functionality on your instrument. + +.. _manage_configs_components: + +Components Tab +~~~~~~~~~~~~~~ + +Components are, in essence, mini configurations. You can use components to "pre-configure" a device (or group of devices) and then include the components in a configuration. The process of creating and managing components is described in :doc:`Create-and-Manage-Components`. + +The Components tab displays two lists of components. The left-hand list shows which components are available to be included in your configuration. The right-hand list shows which components are already included in your configuration. You can only include a component once in a configuration. + +Use the arrow buttons to move components between the two lists. + +.. _manage_configs_iocs: + +IOCs Tab +~~~~~~~~ + +The :doc:`/Key-Concepts-in-IBEX` page describes what an IOC is. In general, you will only wish to include a subset of these in your configuration (i.e. those that correspond to devices on your instrument). + +IOCs need to be explicitly added to the configuration via the IOC tab if you want to change any of their settings such as macros. The IOCs tab shows an overview of all IOCs that are part of the currently viewed configuration. Below the overview table, there are three buttons to add, edit or delete an IOC. + +- The "Edit IOC"-button opens a dialog containing all the settings related to the selected IOC: + + - Auto start: If set, the IOC will be started/restarted whenever the configuration is changed. If not set then if the IOC is not running it will remained stopped after config change, if it is running it will remain running throughout the config change. (Warning: if not set and the IOC is running any changes you make, e.g. a macro change, will not be set on the IOC until you restart it manually.) + - Auto restart: If set, the IOC will be automatically restarted if it is terminated unexpectedly. If the IOC is stopped from the client or writing to the appropriate PV then it will not be restarted. + - The simulation level: By default, the simulation level file is set to NONE, meaning that the IOC will not run in simulation mode. Under normal circumstances, you should not change the default setting. Simulation mode is used for running the IOC without the actual physical device. + - `IOC Macros`_, `IOC PV Values`_ and `IOC PV Sets`_. + +- The "Add IOC"-button opens a dialog which lets you choose from a list of all IOCs available on the instrument. Confirming your selection will take you to the "Edit IOC" dialog for the selected IOC. +- The "Delete IOC"-button allows you to delete IOCs from the list and the configuration. This works with multiple selections, too. + +.. _manage_configs_blocks: + +Blocks Tab +~~~~~~~~~~ +The Blocks tab lists all the blocks that have been defined for the current configuration. When creating a new configuration, the list of blocks will be empty. A :doc:`block ` is, essentially, an alias to a :doc:`PV`. + + +To create a new block, click on the ``Add Block`` button or use the keyboard shortcut ``Ctrl+A``. Blocks can also be copied using the ``Duplicate Block`` button or the keyboard shortcut ``Ctrl+D``. Upon creation of a new block, IBEX displays a dialog to allow you to define the new block. By default, the new block is given the name ``NEW_BLOCK``. You can give the block any name you like, provided the name: + +* contains only the characters a-z, A-Z, 0-9 and _ (underscore). +* starts with a character. +* is unique (on your instrument). + +Below the block name field is the PV address field. Click on the ``Select PV`` button next to the PV address field to choose a PV to be aliased by the block name. + +On clicking the ``Select PV`` button, IBEX will display a list of PVs available on your instrument. There can be a huge number of PVs on an instrument, so the dialog provides some filters to help you narrow your search. Choose PVs from: + + ``All IOCs`` to see PVs from all IOCs on your instrument (this can result in a very long list of PVs). + + ``Active IOCs`` to see PVs only from IOCs that are currently running on your instrument. + + ``Config IOCs`` to see PVs only from IOCs included in the current configuration. + +Interest Level + ``High`` to see PVs considered to be of high interest to scientists + + ``Medium`` to see PVs considered to be of medium interest to scientists (many PVs in this category will be of more interest to technicians and support staff, rather than scientists) + + ``Facility`` to see PVs that relate to a facility, rather than an instrument, devices (PVs in this category typically include PVs relating to the accelerator, target stations, shared beamlines and instrument shutters). + + ``All`` to see all PVs from your selected category of IOCs (again, this can generate a very long list of PVs). + +You can also narrow down the list of PVs by typing the start of the PV name in the ``PV address`` field. For example, if you type ``IN:IRIS:EURO`` you will see only PVs whose address starts with those characters. This is useful if you already know which PV you are looking for. + +Scroll down the list of PVs until you find the one you want. Click on it, to select it and then click on the OK button to return to the Add Block dialog. + +On the Add Block dialog, you can also choose to + +Visible/Local + Toggle the ``Visible`` check-box to make the block visible or hidden. By default, blocks are always visible. This feature is useful, for example, if you need to see blocks while setting up an experiment but don't need to see them once the experiment is running. + + The ``Local`` check-box is used when you need to view PVs from another instrument as blocks. In most circumstances, you will not need to view PVs belonging to another instrument, so you should leave the ``Local`` check-box checked. Facility PVs are an exception to this rule, but IBEX knows about facility PVs and, in this case, automatically sets the ``Local`` check-box to unchecked. If you do need to view PVs belonging another instrument, please consult with the Experiment Controls team. + +Run-Control Settings + Toggle the ``Enabled`` check-box to enable run-control on this block. Use the Low Limit and High Limit fields to define the run-control range (i.e. data is only collected when the block lies within the range). + + Run-control can also be set on non-numbers as boolean or enum values in IBEX are mapped to underlying numbers. For example, a shutter status of OPEN corresponds to a 1 and CLOSED to 0, so setting run control of between 0.5 and 1.5 will put the instrument into waiting when the shutter is not open. In most cases, a 1 will correspond to true and 0 to false, if you are unsure, please consult with the Experiment Controls team. + + When you create a run control for a block it will be used as the default for that configuration. You can temporarily override these values using the `Run-Control menu `_. + + Run controls set on blocks are unique to the configuration. If you would like identical run controls on a block for all configurations, you must set the run control for that block in each individual configuration. + +Logging Settings + Use the Logging Settings section of the Configure Block dialog to control how the value of the block is logged. + + * **Note:** By default logging is enabled (i.e. changes in the value of the block will be logged). + * Click on the ``Enabled`` check-box to change the way the block is logged. If the ``Enabled`` check-box is checked, then logging is enabled. + * You can choose to log the block value periodically (the default period is every 30 seconds). + * Alternatively, you can set a "deadband" - the block will only be logged if its value falls outside +/- the limit defined by the deadband value. + +**PREVIOUS VERSIONS OF IBEX:** In releases 2.1.0 or earlier, the logging is disabled by default. + +To edit an existing block, click on the ``Edit Block`` button or use the keyboard shortcut ``Ctrl+E``. Blocks can be deleted by clicking the ``Delete Block`` button or by using the keyboard shortcut ``DEL``. + +**Note:** Blocks that have been inherited from a component will be shown, but cannot be modified, in the Edit Configuration dialog (the blocks will be shown as "greyed-out"). To modify inherited blocks you need to use the Edit Component dialog (see :doc:`Create-and-Manage-Components`). + +.. _manage_configs_groups: + +Groups Tab +~~~~~~~~~~ +Use the Groups tab to arrange your blocks into convenient groups. You can define as many groups as you wish and you can place as many blocks in each group as you wish, although a block can only appear in one group. + +By default, all blocks are assigned to an automatic group called "Other". By creating new groups, you have the opportunity to override the default assignment and assign blocks to groups of your choosing. + +To create a new group, select the Groups tab and click on the ``Add`` button. IBEX displays a dialog to allow you to define a new group. By default, each new group has the name ``NEW_GROUP``. You can give the group any name you like, provided the name: + +* contains only the characters a-z, A-Z, 0-9 and _ (underscore). +* starts with a character. +* is unique (on your instrument). + +When you click on the ``Add`` button, the dialog displays which blocks are available to be assigned to the new group (i.e. blocks in the "Other" group). + +Use the buttons with the Up and Down arrows to control the ordering of the groups and the order of the blocks within the groups. + +You can select multiple blocks to be added (or removed) from a group using the ``Shift`` and/or ``Ctrl`` keys on your keyboard. + +**Note:** Groups that have been inherited from component will be shown, but cannot be cannot be modified, in the Edit Configuration dialog (the blocks in an inherited group as shown as "greyed-out"). To modify inherited groups you need to use the Edit Component dialog (see :doc:`Create-and-Manage-Components`). + +.. _manage_configs_add_ioc: + +Edit/Add IOC Dialog +------------------- + +The Edit/Add IOC dialogue is opened from the IOC on the New/Edit Configurations/Components dialog. + +.. _manage_configs_ioc_macros: + +IOC Macros +~~~~~~~~~~ + +IOC Macros are configurable values that IBEX can supply to the IOC when the IOC is started. For example, if the IOC is controlling a serial device attached to a COM port, you can use a macro to identify the appropriate port to the IOC. This is especially useful if the device moves between instruments and may be attached to different COM ports on different instruments. Another example of an IOC macro might be the name of a calibration file. + +To set an IOC macro: + +#. Select the IOC Macros tab for the IOC they will be displayed in the table. The columns in the table are: + + #. Macro Name: the name of the macro (e.g. ``PORT``, ``BAUD`` or ``IPADDRESS``) + #. Value: the current value of the macro (e.g. ``COM3``, ``9600`` or ``192.83.42.106``) + #. *v3.7+* Use Default?: whether to not set a value and use the default, if one exists + #. *v3.7+* Default: the default value if one exists, otherwise (no default) or (default unknown) + #. Description: a short description of the macro's purpose + #. Pattern: macro values need to be defined correctly. IBEX uses the pattern to validate the macro value. (For those familiar with such things, the pattern is a "regular expression"). + +#. Choose a macro from the table. The ``Name:`` field (read-only) is populated with the macro name and the ``Value:`` field is populated with the current value of the macro. + +#. Edit the ``Value:`` field to change the macro value. Please note that the value you enter will be validated against the pattern. If the macro does not conform to the pattern, IBEX will display a warning message. IBEX will refuse to accept any values that do not conform to the pattern. + +#. The table of macros will be updated with the new value. You can also use the ``Clear Macro`` button to clear the contents of the ``Value:`` field. + +As of version 5.7, values can be edited directly in the table. Pressing enter or clicking somewhere else will set the value. To clear the value so that it is no longer set, set "Use Default?" to yes. To set the macro to a blank value, i.e an empty string or "", set "Use Default?" to no and leave the value box empty. + +If you are not sure about how to correctly configure macro values for a device, please consult with the Experiment Controls team. + +.. _manage_configs_pv_values: + +IOC PV Values +~~~~~~~~~~~~~ + +IOC PV Values allows you to set the values of a PV when the configuration is first loaded. For example, you may have a CCR in one configuration but a Furnace in another, both using the same Eurotherm. However, the Eurotherm may require the Furnace.txt sensor file for the furnace and the CCR.txt file for the CCR. In this case the we would add a PV Value of + +*IN:INST:EUROTHRM_01:A01:CAL:SEL* *Furnace.txt* + +to the furnace config and + +*IN:INST:EUROTHRM_01:A01:CAL:SEL* *CCR.txt* + +to the CCR config. If you are unsure what PVs you need to write to see :ref:`faq_find_pv` + +**Note**: The value of a PV will remain until it is set to something else. So if a configuration sets it loading another configuration will not set it back to what it was before. + +.. _manage_configs_pv_sets: + +IOC PV Sets +~~~~~~~~~~~ + +IOC PV Sets is an experimental feature within IBEX **do not** use this before talking to the IBEX team. It can be used to load in autosaved values from a specific file setup beforehand. + +**Note**: The value of any PVs will remain until it is set to something else. So if a configuration does this auto-load then loading another configuration will not set it back to what it was before. + +.. _manage_configs_edit_config: + +Editing a Configuration +----------------------- + +To edit a configuration: + +#. Select ``Configurations > Edit`` from the ``Configuration`` menu. +#. IBEX displays the Edit Configuration dialog (as described in `Creating a Configuration`_). +#. This time the Edit Configuration dialog has three buttons at the bottom of the dialog + +Save + Clicking immediately on the ``Save`` button saves your changes without any further prompting. + +Save as... + Clicking on the ``Save as...`` button operates as described in the previous section. You can use the ``Save as...`` button to save the configuration with a new name, before making further changes. + +Cancel + Click on the ``Cancel`` button to exit the Edit Configuration dialog without saving your changes. + +.. _manage_configs_edit_current_config: + +Edit Current Configuration ... +------------------------------ + +To edit the current configuration select ``Edit Current Configuration ...`` from the ``Configuration`` menu. This avoids the need to select the current configuration from a list of configurations. Otherwise, this option behaves in the same way as `Editing a Configuration`_. + +It is always a good idea to check the name of the current configuration before you start editing it - to be sure that you are about to edit the configuration you intended to edit. The :doc:`/gui/Banner` displays the name of the current configuration + +**Note:** When you click on the ``Save`` button when editing the current configuration, the changes you make are applied immediately. There will be a short pause while IBEX re-loads the current configuration and refreshes the display. + +.. _manage_configs_load_config: + +Load a Configuration +-------------------- + +To load a configuration: + +#. Select ``Configurations > Load`` from the ``Configuration`` menu. +#. IBEX displays the Load Configuration dialog, which lists all the configurations defined for your instrument. +#. Select a configuration from the list and press the ``OK`` button +#. IBEX discards the currently loaded configuration and loads the selected configuration. The discarded configuration is not lost - it still exists as a saved configuration and can be reloaded later, if you wish. + +.. _manage_configs_recent_config: + +Recent Configurations +--------------------- + +To load a recent configuration: + +#. Select ``Configurations > Recent`` from the ``Configuration`` menu. +#. IBEX displays the Load Recent Configuration dialog, which lists the last five loaded configurations defined for your instrument and the time at which they were last loaded. +#. Select a configuration from the list and press the ``OK`` button +#. IBEX discards the currently loaded configuration and loads the selected configuration. The discarded configuration is not lost - it still exists as a saved configuration and can be reloaded later, if you wish. + +**Note**: As the current configuration is already loaded, it is not displayed in the list. However, it will be displayed after loading another configuration. + +.. _manage_configs_delete_config: + +Delete a Configuration +---------------------- + +To delete a configuration: + +#. Select ``Configurations > Delete`` from the ``Configuration`` menu. +#. IBEX displays the Delete Configuration dialog, which lists all the configurations defined for your instrument. +#. Select a configuration from the list and press the ``OK`` button +#. IBEX deletes the selected configuration. + +**Note 1:** If you try to delete the currently loaded configuration, IBEX will do nothing. It will not delete the current configuration, because that would leave IBEX unable to communicate with the instrument. If you want to delete the current configuration you need to load a different configuration, then delete the previously loaded configuration. + +**Note 2:** When you delete a configuration it really is deleted. It is no longer available to be used by IBEX. Before deleting a configuration, please be sure that you really do want to delete it. If you unintentionally delete a configuration, please contact the Experiment Controls team - it may be possible to recover the deleted configuration. + +.. _manage_configs_globals: + +Editing a global setting +------------------------ + +Global settings are stored in the configuration directory in a file called ``globals.txt`` (the configuration directory is ``\\config\\\\configurations``). Lines in the file starting with a '#' are comments. Settings are expressed by a line + +``__=`` + +where ``IOC name`` is the name of the IOC on which the macro is set, ``Macro name`` is the name of the macro and value is the value it should have. (**N.B.** that is a double underscore between ``IOC name`` and ``Macro name``). \ No newline at end of file diff --git a/doc/how_to/Create-and-Manage-Device-Screens.rst b/doc/how_to/Create-and-Manage-Device-Screens.rst new file mode 100644 index 0000000..41105b1 --- /dev/null +++ b/doc/how_to/Create-and-Manage-Device-Screens.rst @@ -0,0 +1,57 @@ +Create and Manage Device Screens +################################ + +In IBEX, device screens give you access to a graphical interface to interact with each IOC running on your instrument. + +If the IOC is not running, the device screen will show that the device is disconnected. + +You can have as many device screens as you wish. The device screens need not be for devices in your configuration. + +To view the device screen, double-click on the device in the device screens table and it will appear to the right of the 'Device screens' table by default. + +.. contents:: **Contents** + +Creating a Device Screen +------------------------ + +Click on the 'Edit Device Screens' button just below the Device screens tab to opens the 'Configure Device Screens' dialog box. + +* To create a device screen, click 'Add' in the bottom left-hand corner. +* You can rename the device in 'Name' box in the top right-hand corner. The default name is "Screen". +* To select a device to view, click on the 'Target' drop down box to select the device you want to view. The device does not need to be in your current configuration list of IOCs. However, if the device's IOC is not running, the device screen will show that the device is disconnected. +* Enter the values of any macros needed for the device in the 'Value' box. +* Select 'Save this device screen' to save the device screen to IBEX server. Otherwise, select "Remove this device screen when IBEX is closed". +* Click 'OK' to save the changes you've made to the device screens. Clicking 'Cancel' will close the dialog without saving the changes. + + +Editing a Device Screen +----------------------- + +Click on the 'Edit Device Screens' button just below the Device screens tab to opens the 'Configure Device Screens' dialog box. + +* To edit a device screen, click device screen you want to edit. +* You can then edit the name of the device screen by clicking in the 'Name' box +* You can switch to a different device by clicking the 'Target' drop down box and selecting a different device. +* You can edit the value of any macro by selecting the macro in the 'Properties' table and entering the value of the macro in the 'Value' box. +* Select 'Save this device screen' to save the device screen to IBEX server. Otherwise, select "Remove this device screen when IBEX is closed". +* Click 'OK' to save the changes you've made to the device screens. Clicking 'Cancel' will close the dialog without saving the changes. + +Deleting a Device Screen +------------------------ + +Click on the 'Edit Device Screens' button just below the Device screens tab to opens the 'Configure Device Screens' dialog box. + +* To delete a device screen, click device screen you want to delete. You can delete several different device screens at once by holding down the Ctrl key and selecting the device screens to delete. +* Then click 'Delete' on the bottom left-hand +* Click 'OK' to save the changes you've made to the device screens. Clicking 'Cancel' will close the dialog without saving the changes. + +Special Device Screens +----------------------- + +Live View Device Screen +~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: LiveView.png + :target: LiveView_large.png + +You instrument may have access to a Live View device screen which shows event data from the DAE in real time. This option is only available if your instrument is set up for Live View: it is running in event mode, and your instrument has an arrangement of detectors that can be mapped as a square. If you are in doubt, contact Freddie Akeroyd. \ No newline at end of file diff --git a/doc/how_to/Create-and-Manage-Synoptics.rst b/doc/how_to/Create-and-Manage-Synoptics.rst new file mode 100644 index 0000000..b5c90a2 --- /dev/null +++ b/doc/how_to/Create-and-Manage-Synoptics.rst @@ -0,0 +1,108 @@ +Create and Manage Synoptics +########################### + +In IBEX, synoptic views provide you with interactive, schematic views of your instrument. Each icon on a synoptic view represents a device attached to your instrument. You can tailor the synoptic view to display key PVs next to the device icons. By double-clicking on an item, you can drill down to see more detail. + +You can define as many synoptic views as you wish for your instrument. + +A synoptic need not encompass the whole instrument. You can define synoptic views that focus on specific aspects of your instrument - for example, just the beam optics, or just the sample stack and equipment mounted on the sample stack. + +You can also associate a synoptic view with a particular configuration, so that, in effect, the chosen synoptic becomes the default synoptic for that configuration. + +.. contents:: **Contents** + +Creating a Synoptic View +------------------------ + +To create a synoptic view: + +#. Select ``New`` from the ``Synoptic`` menu. +#. IBEX displays the New Synoptic dialog, which is divided into four panes. + + #. Instrument Tree + #. Component Details + #. Component Target Details + #. PV Details + +#. At the bottom of the dialog are three buttons + +Synoptic Preview + Click on the ``Synoptic Preview`` button to get a preview of how your synoptic will appear. You can click on the ``Synoptic Preview`` button at any time. + +Save as... + Click on the ``Save as...`` button to save your changes. You must provide a name for the synoptic view. The name of the synoptic can contain only the characters a-z, A-Z, 0-9 and _ (underscore). The name must also start with a character. + +Cancel + Click on the ``Cancel`` button to exit the dialog without saving your changes. + +**Please note:** After exiting the New Synoptic dialog, you will need explicitly select the synoptic you have just created to see it displayed in the synoptic display area. + +Use the New Synoptic dialog as follows: + +#. Click on the ``Add Component`` button to add a new component to the Instrument Tree. + + #. When you add a new component, its details are shown in the Component Details pane. It is given the default name ``New Component`` and a default type of ``UNKNOWN``. + #. In the Component Details pane, you can adjust the general properties of the component. + + * Give it a suitable name + * Select the type of device it represents. Click on the drop-down menu to select the device type. + * Click on the ``Add New PV`` button to add blocks or PVs to be associated with the component (remember - blocks are just aliases to PVs). Any blocks or PVs you select will be displayed below the component in the synoptic view. + * Remove any blocks or PVs previously associated with the component. + * You can change the order of components in the synoptic view by dragging & dropping any component to the desired position. As you drag a component, a black line will appear to indicate that you can drop the component and it will be positioned between the two components immediately above and below the black line. + * If you drop a component on top of another component, it will be positioned as "sub-component". "Sub-components" are useful if you have several components that can usefully be grouped together as a composite unit. "Sub-components" are also useful if you have a complex instrument; you can use "sub-components" to create a degree of hierarchy in the synoptic. + + #. If you add an associated block or PV (using the ``Add New PV`` button), its details appear in the PV Details pane. Use the ``Select Block`` or ``Select PV`` buttons to choose a specific block or PV to associated with the component. + + #. Use the Component Target Details pane to adjust the specific properties of the component (e.g. which model of a device the component represents, which component properties are needed). + + * The ``Name:`` field is a drop-down menu. Select the name/model of the device. Some names on the list refer to general classes of device (e.g. ``Eurotherm`` refers to all Eurotherm temperature controllers); other names refer to specific models (e.g. ``Julabo FP300`` refers to a specific model of Julabo water bath). Whether a name is general or specific depends on whether the manufacturer of the device has chosen a common interface to all models of a device or interfaces that are unique to individual models. When you have made your selection, a short description of the component will be displayed in the ``Description:`` field. + * If you are not sure which name/model to select for the ``Name:`` field, click on the ``Default Target`` button. IBEX will then display a list of names/models filtered by the Component Type field (see Component Details pane). This will significantly reduce the size of the list (often there will be only one choice). Choose the most appropriate name/model. + * Clicking on the ``Clear Target`` button will clear any selection in the ``Name:`` field. + * Below the ``Description:`` field is a table of ``Properties:``, which lists the properties belonging to the selected component. Each property has a name and a value. Select each property in turn to edit the value. + * On selecting a property, the value of the property will appear ``Value:`` field. A description of the value is provided in the ``Description:`` field below the ``Value:`` field. The default value might be blank. + * Set the property value. + * **Please note:** Component properties are very specific to individual devices - it is impractical to give definitive advice in a user manual on the correct value for a component property. The ``Description:`` field will provide general advice on the type of value to be entered in the ``Value:`` field. If you are unsure about the correct value to choose, please consult with the Experiment Controls team. + +#. Click on the ``Copy Component`` button to duplicate the currently selected component. If no component is selected, the ``Copy Component`` button is inactive. + +#. Click on the ``Delete Component`` button to delete the currently selected component. If no component is selected, the ``Delete Component`` button is inactive. + +#. Toggle the ``Show Beam`` check-box to show or hide the schematic representation of the beam in the synoptic view. By default, the beam will be shown. + +Editing a Synoptic View +------------------------ + +Editing a synoptic view is similar to creating a synoptic view, except that you are working from an existing synoptic: + +#. Select ``Edit`` from the ``Synoptic`` menu. +#. IBEX displays the Edit Synoptic dialog, which lists all the synoptics defined for your instrument. +#. Choose a synoptic from the list and press the ``OK`` button. +#. IBEX then displays the Edit Synoptic dialog. +#. This time the Edit Synoptic dialog has three buttons at the bottom of the dialog. + +Save + Clicking on the ``Save`` button saves your changes without any further prompting. + +Save as... + Clicking on the ``Save as...`` button operates as described in the previous section. You can use the ``Save as...`` button to save the synoptic with a new name before making further changes. + +Cancel + Click on the ``Cancel`` button to exit the Edit Synoptic dialog without saving your changes. + +**Please note:** After exiting the Edit Synoptic dialog, you might need to click on the ``Refresh Synoptic`` button at the top of the synoptic display area to see the changes you have made. + +Using the Edit Synoptic dialog is the same as the New Synoptic dialog (as described in `Creating a Synoptic View`_). + +Deleting a Synoptic View +------------------------ + +To delete a synoptic: + +#. Select ``Delete`` from the ``Synoptic`` menu. +#. IBEX displays the Delete Synoptic dialog, which lists all the synoptics defined for your instrument. +#. Select a synoptic from the list and press the ``OK`` button +#. IBEX deletes the selected synoptic. + +**Note 1:** If you attempt to delete the current synoptic, IBEX will indeed delete it (you might have to click the ``Refresh Synoptic`` button to see that IBEX really has deleted the current synoptic). + +**Note 2:** When you delete a synoptic it really is deleted. It is no longer available to be used by IBEX. Before deleting a synoptic, please be sure that you really do want to delete it. If you unintentionally delete a synoptic, please contact the Experiment Controls team - it may be possible to recover the deleted synoptic. \ No newline at end of file diff --git a/doc/how_to/How-to-create-PVs-for-generic-user-data.md b/doc/how_to/How-to-create-PVs-for-generic-user-data.md new file mode 100644 index 0000000..86f6e2b --- /dev/null +++ b/doc/how_to/How-to-create-PVs-for-generic-user-data.md @@ -0,0 +1,15 @@ +# Create PVs for generic user data + +The `INSTETC` [IOC](https://github.com/ISISComputingGroup/ibex_user_manual/wiki/Start-and-Stop-IOCs) contains [PVs](https://github.com/ISISComputingGroup/ibex_user_manual/wiki/Process-Variables) intended to be user-settable values. These PVs can have blocks pointed at them [via the configurations screen](https://github.com/ISISComputingGroup/ibex_user_manual/wiki/Create-and-Manage-Configurations#blocks-tab). These PVs could, for example, be used to hold data about equipment which is manually controlled, but should be put in a nexus file. + +There are three types of data that a user PV can hold: integer, real and string. The corresponding process variables are: +- `IN::PARS:USER:I0` for integers +- `IN::PARS:USER:R0` for real types +- `IN::PARS:USER:S0` for strings + +The counter at the end of the PV is an index. By default, instruments are set up to have 5 of each type of user PV (indexes 0-4 inclusive). If you find you need more than 5 of any one data type, it is configurable. +- Go to `C:\Instrument\Settings\config\NDX\configurations` +- Locate a file called `globals.txt` (if it does not exist, create it) +- Add the following line to the file: `INSTETC_01__NUM_USER_VARS=25`, where `25` should be replaced by the maximum number of user variables you want for any given type. +- Ensure that `globals.txt` ends with at least one blank line, otherwise, the last line will not be read. +- To pick up the changes, IBEX will need to be restarted. Follow the process detailed here: [Starting the IBEX Server](https://github.com/ISISComputingGroup/ibex_user_manual/wiki/Starting-And-Stopping-IBEX#starting-ibex-server). \ No newline at end of file diff --git a/doc/how_to/IBEX_initial_training.pptx b/doc/how_to/IBEX_initial_training.pptx new file mode 100644 index 0000000..624c1fe Binary files /dev/null and b/doc/how_to/IBEX_initial_training.pptx differ diff --git a/doc/how_to/LiveView.png b/doc/how_to/LiveView.png new file mode 100644 index 0000000..60c13e1 Binary files /dev/null and b/doc/how_to/LiveView.png differ diff --git a/doc/how_to/LiveView_large.png b/doc/how_to/LiveView_large.png new file mode 100644 index 0000000..a49b769 Binary files /dev/null and b/doc/how_to/LiveView_large.png differ diff --git a/doc/how_to/Manage-the-DAE.rst b/doc/how_to/Manage-the-DAE.rst new file mode 100644 index 0000000..2419815 --- /dev/null +++ b/doc/how_to/Manage-the-DAE.rst @@ -0,0 +1,140 @@ +Manage the DAE +############## + +The Data Acquisition Electronics (DAE) is the hardware which collects neutron or muon data. The DAE is controlled by the ICP (see :doc:`/Key-Concepts-in-IBEX`), which informs the DAE when to start and stop collecting data from the instrument detectors. The ICP also receives sample environment information and combines it with the detector data and is responsible for transferring the final combined dataset to a data file. + +The DAE view communicates with the ICP to control the DAE. The DAE can be managed from the DAE view of the client. The DAE view is split into some tabs and sub tabs which are listed with their functions below. + +.. contents:: **Contents** + +Run Summary +----------- + +The Run Summary tab displays some summary information about the current run and displays any log messages received from the ICP. + +Run Summary Fields +~~~~~~~~~~~~~~~~~~ + +* ``Instrument``: the instrument on which the current run is being performed +* ``Run Status``: status of the current run +* ``Run Number``: the current run number +* ``ISIS Cycle``: the current ISIS cycle +* ``Title``: you can provide a short description of the current run in the ``Title`` field. Click on the ``Set`` button to commit the change (i.e. send it to the ICP, so that it gets included in the data file). To embed block values within the run title see :doc:`/how_to/Add-blocks-to-run-title`. +* ``Show Title in Dataweb Dashboard Page``: set whether to display the title in the :doc:`/The-Web-Dashboard`. This checkbox only affects the Dataweb dashboard; it does not affect the display of the title in IBEX, or the inclusion of the title in the data file. + +Message Log +~~~~~~~~~~~ +The message log area lets you view any messages issued by the ICP. The message log area is the same as the main Log Messages view but filtered to show only messages from the ICP. + +Run Control Buttons +~~~~~~~~~~~~~~~~~~~ + +The Run Summary tab also provides some buttons to control the acquisition of data. Which buttons are available is dependent on the current status of the DAE; this is displayed in the ``Run Status`` field and the IBEX :doc:`/gui/Dashboard`. + +Begin Run + Beginning a run instructs the ICP to tell the DAE to start collecting data. The run status of the DAE will change to BEGINNING and then RUNNING. + +End Run + Ending a run instructs the ICP to tell the DAE to stop collecting data and save the data. The run status of the DAE will change to ENDING (while it saves the data) and then SETUP when it is ready to be started again. + +Pause Run + Pausing a run instructs the ICP to tell the DAE to pause data collection indefinitely. The run status of the DAE will change to PAUSED. The status will remain PAUSED until it is instructed to resume, end or abort the run. + +Resume Run + Resuming a run instructs the ICP to tell the DAE to resume data collection after it has been paused. The run status of the DAE will return to RUNNING. + +Abort Run + Aborting a run instructs the ICP to tell the DAE to stop data collection (as for END). However, the data that has been collected is not written to a file; if a new run is started, then any data that has been collected will be lost. The run status of the DAE will change to SETUP. If this is done mistakenly, the cancel abort button can be used to undo the abort. + +Cancel Abort + This will instruct the DAE to cancel a previous abort. The DAE will be left in a paused state. + +Save Run + This will save the current run data without stopping the current run. + +Experiment Setup +---------------- + +The Experiment Setup comprises of sub-tabs which will have been configured by an ISIS Instrument Scientist. Please do not modify their contents without consulting with the instrument scientist. + +Any changes made are only sent to the DAE when the ``Apply Changes`` button is pressed and will be highlighted until the ``Apply Changes`` button is pressed. If there is a problem with the setting, an error message will appear on the `Run Summary`_ panel. + +Time Channels +~~~~~~~~~~~~~ + +The time channels sub-tab allows the setting of the spectra captured in different time regimes. By setting different step sizes and modes, you can optimise the sizes of the time bins in the final spectra. The setting for the time channels can be set either using the table or by setting a file; usually used when more than 6 regimes are required. The files are stored in the ``configurations/tcb`` directory in the :ref:`installation_layout` on the instrument. + +.. _dae_data_acquisition: + +Data Acquisition +~~~~~~~~~~~~~~~~ + +The data acquisition sub-tab allows you to set up how the DAE will collect the data. The page is split into several sections: + +Tables + The wiring table, detector table and spectra table set the files used when turning signals generated in the detectors into spectra. These files are stored in the ``configurations/tables`` directory in :ref:`server settings ` on the instrument. + +Monitor + Set which spectra number is used for the monitor counts and between which times the spectra should be integrated to return the monitor counts. + +Vetoes + Set which :ref:`vetoes ` are active. + +Muons + Set if and how to collect muon data. + +Timing + Set the source of the :ref:`timing signal ` and how often the data should be auto saved. + +Periods +~~~~~~~ + +The period sub-tab allows the period types and needed parameters to be set up within the DAE. Periods allow data to be collected as if restarting the DAE but without the time overhead of doing this. Software periods are controlled via software command, e.g. genie_python's ``change_period`` command. The other options are hardware controlled, and these are internal (within the DAE) or external control. + +Run Information +--------------- + +The Run Information tab provides a more complete summary of the DAE set up than the Run Summary tab. All the fields on this tab are read-only. + +Spectra Plots +------------- + +The Spectra Plots Tab displays up to 4 spectra plots. The plots show the recorded spectra from the detectors which were set up using the tables in the data acquisition tab. You can choose which spectra are plotted by using the ``Spectrum`` and ``Period`` fields for each plot. Click on the ``Set Plot`` button (positioned at the top right of each plot) to update the plot after changing the ``Spectrum`` or ``Period`` fields. + +Combined Spectra Plot +--------------------- + +The Combined Spectra Plot Tab displays up to 4 spectra plots on the *same graph*. This allows for more direct comparison with one another. The plots show the recorded spectra from the detectors which were set up using the tables in the data acquisition tab. You can choose which spectra are plotted by using the ``Spectrum`` and ``Period`` fields for each plot and make each plot visible or hidden with its corresponding ``Checkbox`` field. + + +Detector Diagnostics +-------------------- + +This tab shows detector diagnostics, the count rate, max and integral for a range of detectors set above. It is possible to show all spectrum with zero or non-zero counts or all the spectra. This can be useful for identifying broken detector tubes. + +The page only updates when it is open on an instrument, so if you are viewing it remotely you may have no information. This is to reduce the load on the server and DAE. + +Vetoes +------ + +The Vetoes tab shows a summary of the vetoes that are in force and their effect for the current run. This information is read-only. Vetoes can only be changed before the start of a run, via the `Data Acquisition`_ sub-tab on the `Experiment Setup`_ tab. + +Simulated DAE +------------- + +The DAE can be placed into a **simulation**/**simulate** mode if you want to do an off-line experiment or test something out when the physical DAE is not usable. In simulation mode the DAE will count frames as normal and has a spectrum count in some spectra but it is not realistic. To turn this on use in genie_python: + +.. code-block:: python + + g.set_dae_simulation_mode(True) + +to switch it off: + +.. code-block:: python + + g.set_dae_simulation_mode(False) + +In simulation mode the dashboard should be coloured correctly and `SIMULATION MODE` is shown in large black letters. +NB All instruments can be placed in simulation mode but some are not set up correctly. If you are having problems please contact us. + +It is also possible to run the DAE and do real counts without the timing signal from ISIS. The setting for this are on :ref:`Experimental Setup -> Data Acquisition tab under Timing ` \ No newline at end of file diff --git a/doc/how_to/Navigate-Synoptics.rst b/doc/how_to/Navigate-Synoptics.rst new file mode 100644 index 0000000..7057e25 --- /dev/null +++ b/doc/how_to/Navigate-Synoptics.rst @@ -0,0 +1,31 @@ +Navigate a Synoptic +################### + +In IBEX, synoptic views provide you with interactive, schematic views of your instrument. Each icon on a synoptic view represents a device attached to your instrument. You can tailor the synoptic view to display key PVs next to the device icons. By double-clicking on an item, you can drill down to see more detail. + +The focus of this page is navigating synoptic views. If you wish to create your own synoptic view see :doc:`Create-and-Manage-Synoptics`. + +.. contents:: **Contents** + +Selecting a Synoptic View +------------------------- + +#. To view an instrument synoptic, click on the :ref:`Synoptic` button on the view selector +#. If a default synoptic has been defined for your current configuration, IBEX will display it. The name of the synoptic will be displayed in the drop-down menu in the area labelled ``Synoptic Selection`` at the top of the synoptic display area. +#. If no default synoptic has been defined for your current configuration, IBEX will display ``--NONE--`` in the drop-down menu in the ``Synoptic Selection`` area and the synoptic display will be blank. +#. You can choose to view any synoptic defined for your instrument by clicking on the drop-down menu in ``Synoptic Selection`` area and choosing any of the synoptics listed. IBEX will refresh the synoptic display to show your chosen synoptic. + +Navigating a Synoptic View +-------------------------- + +The synoptic view represents an instrument in a simplified, schematic form - as a linear sequence of devices. Each device is represented by an icon. Below each icon is an optional set of PVs, which allow you to monitor and/or control aspects of the device represented by the icon. + +If the synoptic is too long to fit in the display area, IBEX will activate a scroll bar at the bottom of the display, to allow you to scroll left and right. + +Clicking on an icon displays a control panel (or OPI) for the device represented by the icon. The device control panel is displayed in a tab on the right-hand side of the IBEX window. Screen space limitations make it impossible to show the full synoptic view alongside a device control panel so, when viewing device control panels, the display area of the synoptic view is reduced, but the left-right scroll bar is activated. + +If you click on a second icon, the control panel for the second device is displayed in a new tab alongside the tab for the first device control panel. You can repeat this action to view the controls panels for further devices. + +You can also display a device control panel by using the drop-down menu in the area labelled ``Synoptic Navigation`` at the top of the synoptic display area. This is a convenient way of displaying a device control panel on large synoptics without having to scroll to find the appropriate device icon. + +When you no longer need to view a control panel, click on the "X" icon at the top right-hand corner of the tab. \ No newline at end of file diff --git a/doc/how_to/Plot-a-Block-Graph.rst b/doc/how_to/Plot-a-Block-Graph.rst new file mode 100644 index 0000000..f05c4f5 --- /dev/null +++ b/doc/how_to/Plot-a-Block-Graph.rst @@ -0,0 +1,70 @@ +Plot a graph of a block +####################### + +IBEX provides a quick, easy way to plot a graph of a block or PV as a function of time (i.e. a "strip-chart"). + +Plot a Graph of a Block +----------------------- + +To plot a graph of a block: + +#. Enable Log Plotter perspective in Preferences -> Select visible perspectives +#. Select :ref:`Log Plotter` from the view selector +#. If you have not previously plotted a block, IBEX displays an empty view, prompting you to select a block. If you have already plotted a block, IBEX restores the graph. +#. To plot a block, simply right-click on a block displayed in the Blocks & Groups view at the top of the IBEX window. +#. Right-clicking displays a pop-up menu and choose ``Display block history`` from the menu. Here you can either add the trace for this block to an existing plot, or create a new, separate plot. +#. IBEX displays a graph of the selected block as a function of time. + +The graph axes will automatically adjust to the range of values that the selected block has experienced. The graph axes are labelled with the name of the underlying PV (remember, blocks are aliases to PVs). + +Plot a Graph of a PV +-------------------- + +You can choose a PV to be plotted from any OPI, in the same way as choosing a block. Simply right-click on the PV and select ``Process Variable`` > ``Log Plotter`` from the menu. + +Plot a Graph of the Runstate +---------------------------- + +Currently the runstate is not easily plottable from a context menu but you can add it manually to a plot. You can do this by right clicking on a plot and selecting ``Add PV`` then enter under name ``IN:%INST%:DAE:RUNSTATE.VAL``, replacing %INST% with the name of your instrument (e.g. ``IN:IMAT:DAE:RUNSTATE.VAL``. This will then show the runstate on the graph with the following values: + +#. SETUP +#. RUNNING +#. PAUSED +#. WAITING + +Higher numbers are transitional states, beginning etc. + +Changing the Appearance of a Graph +---------------------------------- + +Along the top of the graph are a series of buttons which allow you to adjust the appearance of the graph. + +Right clicking on the y-axis allows you to quickly toggle settings such as auto-scale and grid lines, or to edit the axis name and range. + +For more advanced adjustments, you can right-click and select 'Open Properties Panel' which will open a panel to the right of the graph (by default), which give you more granular control of the appearance of your graph or plot. + +The 'When archived data arrives, perform stagger' option under 'Value Axis', when selected, will re-scale and stagger the graph whenever it fetches archived data, for example when adding another block to the graph or increasing the time window. + +Plotting Multiple Traces on the Same Axis +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The log plotter allows you to display multiple traces on the same value axis so they scale together. The way to do this is as follows: + +1. Right click on the graph and select ``Open Properties Panel`` +2. In the ``Traces`` tab, find the column titled ``Axis`` +3. In the row of any trace, click the axis entry, then select the axis of the trace you want to add it to from the drop-down list. +4. They will now be displayed along the same value axis. + +As of Release Version 5.5, you can right click on the block you want to add and select the option to add to an existing axis. + + +Adjusting Time Axis on Log Plotter +---------------------------------- +The time axis can be manipulated to adjust its start and end time using the ``Time`` option. This option could be found under the plotted PVs tab. + +.. image:: log_plotter_time.png + +The following pop-up window will show up once the ``Time`` option is chosen. + +.. image:: time_scale_menu_open.png + + \ No newline at end of file diff --git a/doc/how_to/Start-and-Stop-IOCs.rst b/doc/how_to/Start-and-Stop-IOCs.rst new file mode 100644 index 0000000..cf69fb6 --- /dev/null +++ b/doc/how_to/Start-and-Stop-IOCs.rst @@ -0,0 +1,18 @@ +Start and Stop IOCs +################### + +In `EPICS `_ an IOC is a component which controls hardware devices. In IBEX, we use IOCs to control sample environment devices attached to instruments. The acronym IOC stands for Input/Output Controller. As the name suggests, an IOC controls the communication between a hardware device and other parts of IBEX. + +In order to communicate with a hardware device, the corresponding IOC must be running. The ``IOC`` menu in IBEX provides the means to start IOCs (and to stop IOCs, when they are no longer required). + +Starting or Stopping an IOC +--------------------------- +To start, stop or restart an IOC: + +#. Select ``Start/Stop IOCs`` from the ``IOC`` menu. +#. IBEX displays a dialog containing a list of all the IOCs available on the instrument. The list shows whether each IOC is running or stopped. +#. Find the IOC you want in the list and use the buttons at the bottom to start, stop or restart that IOC. + +It might take a few moments from pressing the button for the selected IOC to fully start itself up or fully shut itself down. You might also see a number of messages written to the :ref:`IOC Log` as the IOC starts up or shuts down. + +**Note**: The effect of auto-restart has no effect on the stop action. Stop will stop the IOC and it will not restart. \ No newline at end of file diff --git a/doc/how_to/log_plotter_time.png b/doc/how_to/log_plotter_time.png new file mode 100644 index 0000000..50425b7 Binary files /dev/null and b/doc/how_to/log_plotter_time.png differ diff --git a/doc/how_to/time_scale_menu_open.png b/doc/how_to/time_scale_menu_open.png new file mode 100644 index 0000000..aee02bf Binary files /dev/null and b/doc/how_to/time_scale_menu_open.png differ diff --git a/doc/ibex_client_large.png b/doc/ibex_client_large.png new file mode 100644 index 0000000..f6253b7 Binary files /dev/null and b/doc/ibex_client_large.png differ diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..10ed5c6 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,54 @@ +# IBEX User Manual + +Welcome to the IBEX user manual. + +- **Not sure what IBEX is?** Start with [the introduction to IBEX](introduction/What-Is-IBEX). +- **Asking for help or reporting a problem?** The instructions for doing so are in [the FAQ](#report_a_problem). +- **Unsure what some IBEX terminology means?** The [Glossary](Glossary) or [Concepts](Key-Concepts-in-IBEX) pages +may be helpful. +- **Looking for a file or folder in IBEX?** See [the 'Where is ...?' guide](IBEX-File-Paths-page). +- **Unsure how to do something in IBEX?** There is information in [the FAQ](FAQ), +[the how-to guide](How-To), and the feature-specific, [device-specific](Device-Specific-Guidance), or +[instrument-specific](Instrument-Specific-Guidance) guides. + +--- + +```{toctree} +:caption: Overview +:maxdepth: 1 +:titlesonly: + +Introduction +Key-Concepts-in-IBEX +FAQ +Glossary +``` + +```{toctree} +:caption: Features +:maxdepth: 1 +:titlesonly: + +IBEX-GUI-Features +Scripting +Script-Generator +The-Web-Dashboard +``` + +```{toctree} +:caption: Guides +:maxdepth: 1 +:titlesonly: + +How-To +IBEX-File-Paths-page +Instrument-Specific-Guidance +Device-Specific-Guidance +Obsolete +``` + +## Further information & Links +- [Project Management Wiki](https://github.com/isiscomputinggroup/ibex/wiki) - documents the IBEX Project (formerly +known as the Instrument Control Project). +- [Developer's manual](https://isiscomputinggroup.github.io/ibex_developers_manual/) - documentation targeted at +developers, contains detailed information about specific IBEX components. diff --git a/doc/inst_specific/Engin-X-Sample-Stack.md b/doc/inst_specific/Engin-X-Sample-Stack.md new file mode 100644 index 0000000..159c20d --- /dev/null +++ b/doc/inst_specific/Engin-X-Sample-Stack.md @@ -0,0 +1,21 @@ +# Engin-X Sample Stack + +The Engin X Sample Stack is controlled through IBEX but underneath IBEX link back into LabVIEW VIs from SECI hence why there are some special steps you need to use when looking at it. If you can't find the answer you are looking for in this page there is more information in the [developer wiki but beware this is quite low level](https://isiscomputinggroup.github.io/ibex_developers_manual/specific_iocs/motors/EnginX-Sample-Positioner.html). + +## Define a Motor Position on the Engin-X Sample Stack +- Using a file explorer, go to the following location on `ndxenginx`: `C:\Labview Modules\Drivers\Galil DMC2280` +![](https://raw.githubusercontent.com/wiki/ISISComputingGroup/ibex_user_manual/enginx_sample_stack_1.png) +- Double click on the file Galil – System Functions.llb +![](https://raw.githubusercontent.com/wiki/ISISComputingGroup/ibex_user_manual/enginx_sample_stack_2.png) +- Double click on the file in the top section called “Galil – Table of motor details.vi”. The following LabVIEW vi will appear – but populated with the motors for ENGINX +![](https://raw.githubusercontent.com/wiki/ISISComputingGroup/ibex_user_manual/enginx_sample_stack_3.png) +- IMPORTANT: Select the correct motor on the left hand side. +- Select the tab called Tools. +![](https://raw.githubusercontent.com/wiki/ISISComputingGroup/ibex_user_manual/enginx_sample_stack_4.png) +- Select “Enable” +![](https://raw.githubusercontent.com/wiki/ISISComputingGroup/ibex_user_manual/enginx_sample_stack_5.png) +- Enter the new position in “Define Motor Position”. +- Enter the new position in “Define Encoder Position” +- Click the two “Apply” buttons next to these controls +![](https://raw.githubusercontent.com/wiki/ISISComputingGroup/ibex_user_manual/enginx_sample_stack_6.png) +- Minimise the vi (DO NOT STOP the VI). IBEX uses this in the background to perform the motion control for the sample stack. diff --git a/doc/inst_specific/Guidance-on-Writing-Scripts-for-the-Muon-Front-End.rst b/doc/inst_specific/Guidance-on-Writing-Scripts-for-the-Muon-Front-End.rst new file mode 100644 index 0000000..bfe5675 --- /dev/null +++ b/doc/inst_specific/Guidance-on-Writing-Scripts-for-the-Muon-Front-End.rst @@ -0,0 +1,132 @@ +Muon Front End Scripting +######################## + +This page contains guidance on writing scripts for the Muon Front-End control PC (NDEMUONFE). The information on this page is specific to NDEMUONFE and is not relevant to other control PCs. + +.. contents:: **Contents** + +Starting & Stopping Runs Remotely +--------------------------------- + +Ensuring the control machine has sufficient permission to begin a run +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The relevant code can be found in the GitHub repository: + +https://github.com/ISISComputingGroup/mfe_control_scripts + +The code is written in Python and relies on the win32com module. Please ensure this module is installed before running. + +There is a file, run_interactively.py, which can be used to trigger commands on multiple machines interactively. It is currently set up to run on the 3 MFE instrument PCs. You can adjust it by changing the list of machine names in the variable MACHINES. To run just launch the script with Python. + +Note that the script relies on the host machine and user having sufficient DCOM permissions to talk to the three instrument machines which can be achieved through the Windows credential manager. + +1. Go to the start menu +2. Type "Credential Manager" and open the Credential Manager +3. You will need the credentials for all the machines you want to connect too. The "Persistence" field for the credentials must be "Enterprise" or higher (not "Local machine"). +4. To add a new credential + 1. Click "Add a Windows credential" + 2. Enter the credentials (e.g. NDXMUSR, NDXMUSR\\spudulike, [PASSWORD]) + 3. Click "OK" + +Using the script to control the runs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To write your scripts, use the MultipleDaeController class in Python to issue commands to multiple machines simultaneously. The script run_interactively.py provides a good example of how to use it. + +:: + + from multiple_dae_controller import MultipleDaeController + controller = MultipleDaeController() + waitfor_seconds = 10 + for m in ["NDXHIFI","NDXMUSR","NDXEMU"]: + controller.add_machine(m,waitfor_seconds) + controller.run_on_all("get_run_state") + controller.run_on_machines("end",["NDXHIFI","NDXMUSR"]) + controller.run_on_machine("begin","NDXEMU") + +The following methods are currently supported: + +- begin +- end +- pause +- resume +- abort +- get_run_state +- get_events +- get_frames +- get_counts +- waitfor_counts +- waitfor_frames +- waitfor_events + +Using Blocks to Write Tuning Control Scripts +-------------------------------------------- + +A configuration_ with blocks should be created as for any IBEX instrument on NDEMUONFE. + +.. _configuration: CreateandManageConfigurations + +On an appropriate system, import `genie\_python`_ to Mantid, and set your instrument to be "MUONFE", then get the associated blocks. + +:: + + set_instrument("MUONFE") + get_blocks() + +You should now get a list of blocks on the remote system. These can then be used as standard for scripting by writing to and from those values. + +Return to `Contents`_. + +How to alter write access to blocks for each instrument +------------------------------------------------------- + +The initial gateway setup has been undertaken. Should the computers being provided control need to be changed, then the gateway should be restarted at the very least, and it would be wise to consider restarting the whole server. + +For any system in R55 which requires full control of all aspects of NDEMUONFE ensure that there is an entry in globals.txt on NDEMUONFE of the format + +:: + + ACF_IH1=computer_name + +You can specify up to four of these. + +Gateway settings have been set up to allow NDX and NDL systems to control each instrument respectively (so the items used by MUSR have write access from MUSR). There are more detailed instructions on how to set up these aspects of the gateway :external+ibex_developers_manual:doc:`in the developer's manual ` + +Machines listed in the globals.txt can be restricted to read-only access by sending the following command: + +:: + + caput IN:MUONFE:CS:EXCLUSIVE 1 + +There is a similar PV for each instrument, so to limit HIFI to read-only: + +:: + + caput IN:MUONFE:CS:EXCLUSIVE:HIFI 1 + +Or to allow for writing to the EMU values: + +:: + + caput IN:MUONFE:CS:EXCLUSIVE:EMU 0 + +How to Re-apply Settings +------------------------ + +IOCs controlling Power Supply Units (PSUs) have the option to re-apply their set-points (current, voltage, status on/off) the next time they are restarted. The following may be useful if, for any reason, the PSUs are restarted and lose their set-points, and you need a quick way to re-apply them all at once rather than manually one by one. + +The relevant configuration must be set up in the following way: + +#. Open the Edit Configuration dialog (by selecting ``Configurations > Edit`` from the ``Configuration`` menu). +#. In the ``IOCs`` tab, locate the correct IOC and make sure both the ``Auto-start?`` and ``Auto-restart?`` boxes for the IOC are checked. +#. In the ``IOC Macros`` tab, select the correct IOC and set the macro ``SP_AT_STARTUP`` to ``YES`` (default is ``NO``). + +The set-points can be re-applied by reloading the current configuration (which will restart the IOCs), with the following `genie\_python`_ command: + +:: + + reload_current_config() + +Note that the set-points can also be re-applied by restarting the IOCs individually in the IBEX GUI (as long as the ``SP_AT_STARTUP`` macro is set as above). + +.. _`genie\_python`: http://shadow.nd.rl.ac.uk/genie\_python/sphinx/genie\_python.html \ No newline at end of file diff --git a/doc/inst_specific/IMAT-motors.rst b/doc/inst_specific/IMAT-motors.rst new file mode 100644 index 0000000..87cbfeb --- /dev/null +++ b/doc/inst_specific/IMAT-motors.rst @@ -0,0 +1,15 @@ +IMAT Motors +########### + +There are many motors on IMAT this page contains some details about what happens if there is a power cut. + +Jaws +---- + +There are jaws on Galil 1 (axis 5,6,7,8) and then all axes on Galil controllers 2 and 3. These all have homing routines and can be homed together (there is a script :code:`g.home_`) which will home all axis. If the axis appears not to move the IOC should be restarted; this will reload programs and settings into the Galil controller. + +Sample Stack +------------ + +The sample stack Sample Stack X and Sample Stack Y use absolute encoders. After a power cut the IOC should be restarted and then it needs to be reset. Currently to do this drill down to the more details level and then click ueip (use encoder if present) No then yes. This resets the motor steps in the Galil controller and thus allows the motor to move. + diff --git a/doc/inst_specific/enginx_sample_stack_1.png b/doc/inst_specific/enginx_sample_stack_1.png new file mode 100644 index 0000000..6ae69ea Binary files /dev/null and b/doc/inst_specific/enginx_sample_stack_1.png differ diff --git a/doc/inst_specific/enginx_sample_stack_2.png b/doc/inst_specific/enginx_sample_stack_2.png new file mode 100644 index 0000000..98a97f9 Binary files /dev/null and b/doc/inst_specific/enginx_sample_stack_2.png differ diff --git a/doc/inst_specific/enginx_sample_stack_3.png b/doc/inst_specific/enginx_sample_stack_3.png new file mode 100644 index 0000000..fe4ad01 Binary files /dev/null and b/doc/inst_specific/enginx_sample_stack_3.png differ diff --git a/doc/inst_specific/enginx_sample_stack_4.png b/doc/inst_specific/enginx_sample_stack_4.png new file mode 100644 index 0000000..e3eb23f Binary files /dev/null and b/doc/inst_specific/enginx_sample_stack_4.png differ diff --git a/doc/inst_specific/enginx_sample_stack_5.png b/doc/inst_specific/enginx_sample_stack_5.png new file mode 100644 index 0000000..d91395b Binary files /dev/null and b/doc/inst_specific/enginx_sample_stack_5.png differ diff --git a/doc/inst_specific/enginx_sample_stack_6.png b/doc/inst_specific/enginx_sample_stack_6.png new file mode 100644 index 0000000..d91395b Binary files /dev/null and b/doc/inst_specific/enginx_sample_stack_6.png differ diff --git a/doc/inst_specific/enginx_sample_stack_7.png b/doc/inst_specific/enginx_sample_stack_7.png new file mode 100644 index 0000000..d91395b Binary files /dev/null and b/doc/inst_specific/enginx_sample_stack_7.png differ diff --git a/doc/introduction/Installing-IBEX.rst b/doc/introduction/Installing-IBEX.rst new file mode 100644 index 0000000..26a1e1a --- /dev/null +++ b/doc/introduction/Installing-IBEX.rst @@ -0,0 +1,63 @@ +Installing IBEX +############### + +.. contents:: **Contents** + +.. _installing_ibex_client: + +Installing IBEX Client +---------------------- + +Installation of IBEX client on a PC is simple and straightforward. + +Pre-requisites for running IBEX Client +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The IBEX client is designed to run on Windows 10, and so long as that is up to date that should be enough for the client. +It may run on Windows 11, but there is no support for that at present. +It can run on Linux, and there is a build available for use on IDAAS, it is not supported in other Linux environments at present. + + +Installation +~~~~~~~~~~~~ + +There is a network drive location that the experiment controls group can direct you to. + +.. _installation_layout: + +Installation Layout +------------------- + +After installation, the current paths are used by the various components. + ++-------------------------------------------------------+-------------------------------------------------------------------+ +| Item | Path | ++=======================================================+===================================================================+ +|IBEX Client | ``C:\Instrument\Apps\Client_E4`` | ++-------------------------------------------------------+-------------------------------------------------------------------+ +| genie_python (include python and dependencies) | ``C:\Instrument\Apps\Python3`` | ++-------------------------------------------------------+-------------------------------------------------------------------+ +| EPICS utilities | ``C:\Instrument\Apps\Python3\EPICS_UTILS`` | ++-------------------------------------------------------+-------------------------------------------------------------------+ +| Server Code and executables | ``c:\Instrument\Apps\EPICS`` | ++-------------------------------------------------------+-------------------------------------------------------------------+ +| Server Settings | ``C:\Instrument\Settings\config\\configurations`` | ++-------------------------------------------------------+-------------------------------------------------------------------+ +| Common settings files (e.g. sensor calibration files) | ``C:\Instrument\Settings\config\common`` | ++-------------------------------------------------------+-------------------------------------------------------------------+ +| Server logs, autosave and database files | ``C:\Instrument\Var`` | ++-------------------------------------------------------+-------------------------------------------------------------------+ + +.. _installing_ibex_server: + +Installing IBEX Server +---------------------- + +Most instruments at ISIS are now using at IBEX, with the last few being planned for migration during 2024 and early 2025. +If you need to install the server on an Instrument, please contact the Experiment Controls team. +`The developers manual `_ holds more detailed information should it be needed. + +Uninstalling IBEX +----------------- + +Uninstallation of IBEX is performed by manually deleting the relevant directories as listed in :ref:`installation_layout`. \ No newline at end of file diff --git a/doc/introduction/Starting-and-Stopping-IBEX.rst b/doc/introduction/Starting-and-Stopping-IBEX.rst new file mode 100644 index 0000000..5e68a30 --- /dev/null +++ b/doc/introduction/Starting-and-Stopping-IBEX.rst @@ -0,0 +1,88 @@ +Starting and Stopping IBEX +########################## + +.. contents:: **Contents** + +Starting and Stopping IBEX Client +--------------------------------- + +.. _starting_ibex_client: + +Starting IBEX Client +~~~~~~~~~~~~~~~~~~~~ + +To start IBEX Client, select IBEX from the Start icon on the taskbar of your Windows PC. If you use IBEX regularly, it will appear in the menu of frequently used programs as soon as you click on the Start icon. + +If you have not used IBEX for some time, it might not appear on the list of frequently used programs. In this case, you can navigate to IBEX by using the Search box on the Start menu. + +Alternatively, if you created a desktop short-cut to the IBEX client, double-click on the icon. + +If you are on an Instrument control computer, then there may well be a shortcut pinned to the taskbar as well which you can click to launch the client. + +.. _stopping_ibex_client: + +Stopping IBEX Client +~~~~~~~~~~~~~~~~~~~~ + +To stop the IBEX client, select ``Exit IBEX Client`` from the ``IBEX`` menu, or clock on the ``close`` button in the top right hand corner. IBEX will prompt you to confirm that you are sure you wish to exit. Confirm that you wish to exit and the IBEX client will shut down. + +**Please Note:** Stopping the IBEX client does not stop the IBEX server. The IBEX server will continue to run after you have stopped the IBEX client. You can re-connect to the IBEX server the next time to start the IBEX client. + +Starting and Stopping IBEX Server +--------------------------------- + +The IBEX Server is designed to run continuously. There is no particular need for it to be started and stopped on a regular basis. If you find yourself doing so please do ensure that you have informed the experiment controls team about this, and what the trigger may be. + +The IBEX Server is a collection of mutually cooperating processes. To start and stop the IBEX Server, these processes need to be started and stopped in the correct order - there are scripts which ensure that these processes are started and stopped correctly. Please use the appropriate script (as described below) to start and stop IBEX Server. + +.. _starting_ibex_server: + +Starting IBEX Server +~~~~~~~~~~~~~~~~~~~~ + +On the instrument control PC, there should be a shortcut which will allow you to start the server in the programs list. This is called ``start_ibex_server.bat``. This shortcut will point to a file of that name in ``C:\Instruments\Apps\EPICS``. + +This will start the server, and prompt you to wait for the ``IBEX Server Started`` message, wait for that message and then you can proceed to start the client and use the system. + +.. _stopping_ibex_server: + +Stopping IBEX Server +~~~~~~~~~~~~~~~~~~~~ + +If you want to stop running the server, it is probably best to make sure you have stopped your client. + +Similar to the ``start_ibex_server.bat`` there is a ``stop_ibex_server.bat`` which you can usually access in the same ways. There will either be a shortcut in your start menu, which points to a file in the EPICS directory. + + +Starting and Stopping IBEX Server After/Before Running SECI +----------------------------------------------------------- + +There is a special case when you want to swap from IBEX to SECI when SECI is using IBEX as a *mini-inst* (this means IBEX is running an underlying ioc like the JASCO pump or a special DAE process). In this case there are multiple files that need to be changed to run in the two modes. To facilitate swapping there are scripts to allow you to do this easily. + +Starting IBEX Server after running SECI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To start IBEX Server after running SECI, proceed as follows: + +#. Use Windows Remote Desktop Connection to log in to your instrument control PC +#. Open a command window +#. At the command prompt type the following:: + + cd c:\Instrument\Apps\EPICS + start_ibex_server_close_seci.bat + +#. Allow the script a few minutes to complete. + +Stopping IBEX Server before running SECI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To stop IBEX Server and then start SECI, proceed as follows: + +#. Use Windows Remote Desktop Connection to log in to your instrument control PC +#. Open a command window +#. At the command prompt type the following:: + + cd c:\Instrument\Apps\EPICS + stop_ibex_server_start_seci + +#. Allow the script a few minutes to complete. diff --git a/doc/introduction/What-Is-IBEX.rst b/doc/introduction/What-Is-IBEX.rst new file mode 100644 index 0000000..bb2b87f --- /dev/null +++ b/doc/introduction/What-Is-IBEX.rst @@ -0,0 +1,31 @@ +What is IBEX +############ + +IBEX is the name of a suite of software which helps to control the beamlines for experiments at ISIS, as well as generating the data files which are then digested and made available via the `ISIS Data Gateway `_. + +IBEX consists of a server and Graphical User Interface (GUI) system, which can be run on separate computers if appropriate. + +IBEX uses python as its scripting language. genie_python is a python library that allows the scripts written for IBEX to match closely in format to those in the previous control system used at ISIS. + +.. contents:: **Contents** + +The IBEX Server +--------------- + +You can find out more about the IBEX server :ref:`here`. + +The IBEX GUI +------------ + +Using the IBEX GUI is the primary focus of this whole manual, as it is through the GUI that you will typically interact with IBEX. + +Introduction to genie_python +------------------------------------------------ + +A full reference to genie_python is available `on GitHub `_ or internally `on shadow `_. + +Previous Instrument Control at ISIS +------------------------------------------------ +You can find out more about the previous control system, SECI, and how it relates to IBEX :doc:`here<../obsolete/Previous-Instrument-Control-at-ISIS-‐-SECI>`. + + diff --git a/doc/logo.svg b/doc/logo.svg new file mode 100644 index 0000000..49326a2 --- /dev/null +++ b/doc/logo.svg @@ -0,0 +1,9 @@ + + ibex-logo + + + + diff --git a/doc/nicos_changes.ppt b/doc/nicos_changes.ppt new file mode 100644 index 0000000..50a3953 Binary files /dev/null and b/doc/nicos_changes.ppt differ diff --git a/doc/obsolete/Converting-Open-GENIE-to-genie_python.rst b/doc/obsolete/Converting-Open-GENIE-to-genie_python.rst new file mode 100644 index 0000000..3b7f754 --- /dev/null +++ b/doc/obsolete/Converting-Open-GENIE-to-genie_python.rst @@ -0,0 +1,66 @@ +Converting Open GENIE to genie\_python +====================================== + +.. warning:: + This guide is obsolete; Open GENIE is no longer in use on any instrument. + +If you know a little bit of Python already, converting Open GENIE +scripts to ``genie_python`` is very often straightforward. Even if +you're new to Python, once you know a few simple pieces of syntax, +you'll be able to convert many scripts without issue. + +**Note:** If you are new to Python, consult the :external+mantid:ref:`introduction_to_python` on the Mantid web-site. + +List of functions +----------------- + +We've included some `common genie_python +commands <#common-genie_python-commands>`__ on this page, but for a full +list refer to the :external+genie_python:py:mod:`genie` reference documentation. + +Indentation +----------- + +One thing where there is no direct comparison between Python and Open GENIE is with **indentation**. +In Python, different code blocks are identified by their indentation +level. In many programming languages, code blocks are encased in curly +braces (``{...}``), but Python uses indentation. For example: + +:: + + print "No indent" + def my_func(): + print "1 indent. Inside the function" + if True: + print "2 indents. Inside the if clause" + print "2 indents. Still inside the if clause" + print "1 indent. In the function but not the if clause" + print "No indent. Outside the function" + +Typically an ``indent`` is 3 or 4 spaces. Tabs can be used too, but +Python won't recognise that a tab is the same as 4 spaces so can lead to +problems. It's often best to avoid them. This might be a new concept if +you've only ever written Open GENIE, but trust us in that it opens up a +lot of ways to make scripts more powerful, easier to read and more +reliable. + +Side-by-side comparison +----------------------- + ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Open GENIE syntax | ``genie_python`` syntax | Comments | ++===================================+===============================================+=========================================================================================================================================================================================================================================================================================================================+ +| PROCEDURE ``my\_func`` | ``def my\_func():`` | This is the standard way to define a function in Python | ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``begin`` | ``g.begin()`` | Many functions in ``genie_python`` have the same name as in Open GENIE. In these cases, prepend ``g.`` to indicate the method belongs to ``genie_python`` and append ``()`` to tell Python to execute the method with no arguments | ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``my\_func\_2 100`` | ``my\_func\_2(100)`` | To execute a function, give its name and then the argument in brackets. This is a user-defined function, not a ``genie_python`` function, so it has no ``g.`` in front. | ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``my\_func\_3 100 200`` | ``my\_func\_2(100,200)`` | As above, except that multiple arguments are separated by a comma | ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``waitfor seconds=20`` | ``g.waitfor(seconds=20)`` | Some methods can take named arguments. In these cases you simply give named arguments in the form ``[name]=[value]``. Note that you can mix named and unnamed arguments, but unnamed arguments always appear at the start of the argument list. `This section <#argument-ordering>`__ gives a more detailed description | ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``cset/nocontrol MY_BLOCK=value`` | ``g.cset('MY_BLOCK',value,runcontrol=False)`` | Some Open GENIE commands take optional arguments. The same principle applies as in the above example. | ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``# This is a comment`` | ``# This is a comment`` | Comments are the same in both languages | ++-----------------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ \ No newline at end of file diff --git "a/doc/obsolete/Previous-Instrument-Control-at-ISIS-\342\200\220-SECI.rst" "b/doc/obsolete/Previous-Instrument-Control-at-ISIS-\342\200\220-SECI.rst" new file mode 100644 index 0000000..ea9646b --- /dev/null +++ "b/doc/obsolete/Previous-Instrument-Control-at-ISIS-\342\200\220-SECI.rst" @@ -0,0 +1,37 @@ +SECI +#### + +.. warning:: + This page is obsolete; all instruments have migrated from SECI to IBEX. + +IBEX is replacing the Sample Environment Control Interface (SECI) as the primary instrument control software. + +Before the development of IBEX, most device control was performed using LabVIEW, with SECI providing an integrated view of the various LabVIEW VIs. IBEX, on the other hand, is designed to use EPICS to provide device control. LabVIEW will not disappear entirely; when LabVIEW is required, it can be wrapped in EPICS. + +SECI used a scripting language known as Open Genie to aid in the automation of experiments at the facility. + +.. contents:: **Contents** + + +IBEX and SECI Similarities +-------------------------- + +IBEX and SECI both provide integrated views for controlling neutron & muon instruments. SECI integrates information from LabVIEW VIs; IBEX integrates information from EPICS IOCs. In SECI, it is the LabVIEW VIs that directly control the individual devices attached to an instrument. In IBEX, the EPICS IOCs fulfil the role performed by the LabVIEW VIs. + +IBEX and SECI also share similar UIs, partly because they perform similar functions, but mainly by design - if they behave in similar ways, then it is easier to switch from SECI to IBEX. + +IBEX and SECI Differences +-------------------------- + +IBEX is a client-server based system. The server components of IBEX run on the instrument control PC and directly control the instrument. The IBEX client is a GUI, which provides an integrated view of the information provided by the server components. The IBEX client typically runs on a separate PC (which could be in the instrument cabin, pod, or even your office). + +It is important to realise that the IBEX client is not the instrument control program. The server components of IBEX collectively constitute the instrument control program. The IBEX client provides a convenient way to communicate with the server components. You can thus close the IBEX client without stopping control of devices; you can even run multiple instances of the client on the same or different computers. You can also run the IBEX client on the instrument control PC. + +In SECI, the LabVIEW VIs all run as processes on a single PC - the instrument control PC. By contrast, in IBEX, all the server components (and the IBEX client, for that matter) are independent processes that can run anywhere on the ISIS network. Because of this, IBEX has a more flexible architecture - new components can be introduced into the architecture more easily, control processes can be distributed across multiple PCs (if necessary), instruments can more easily share infrastructure. + +In practice, in most cases, the IBEX server components will continue to run (as independent processes) on a single control PC. However, depending on individual circumstances, we will choose to run some server components on further control PCs. For example, some devices have their own dedicated control PC (e.g. cameras on IMAT). By contrast, some instruments (e.g. muon instruments) need to share infrastructure (again, controlled by a dedicated PC). The IBEX architecture provides the flexibility to accommodate both types of arrangement in a transparent fashion. + +Differences between Open Genie and genie_python +------------------------------------------------ + +A detailed description of the differences is available in :doc:`/Scripting`. \ No newline at end of file diff --git a/doc/obsolete/Switching-Between-IBEX-and-SECI.md b/doc/obsolete/Switching-Between-IBEX-and-SECI.md new file mode 100644 index 0000000..d32d0e0 --- /dev/null +++ b/doc/obsolete/Switching-Between-IBEX-and-SECI.md @@ -0,0 +1,34 @@ +# Switching between IBEX & SECI + +:::{warning} +This guide is obsolete; there are no longer any instruments running SECI. +::: + +When an existing instrument is migrated to IBEX, the SECI installation is not deleted. This allows the instrument to temporarily switch back to SECI if needed for a particular experiment. During normal hours, you can contact the IBEX team for assistance, but this section will cover how you can carry out this yourself and any matters to watch out for. Please let the IBEX team know of the reason you needed to move back to SECI if they are not already aware. + +Switching between SECI and IBEX is possible as they both use the same underlying DAE control software (ISISICP) and sample environment logging database. This means that the run number is preserved etc. as well as other details. + +However, the following points should be born in mind: +- Only swap when in SETUP mode and you are sure any raw/nxs data file has completed being written. The control program writes files asynchronously in the background, so just being in SETUP does not guarantee that file writing has been completed. When in event mode, the file write can happen a while afterwards. So you should check the file from the last run number has appeared on the data archive (Usually d: network drive) before continuing. +- Don't have both SECI and IBEX running at the same time; they will likely try and talk to the same devices +- You may get at least one raw data file containing sample environment data from both SECI and IBEX; this is because a run contains all data from the end of the previous run up until when it ends. If this would cause confusion (maybe there are blocks in SECI and IBEX with the same name that don't mean the same thing), do a BEGIN/END to create a file and so put this data elsewhere. + +## Procedure + +### If SECI is running and you want to start IBEX: + +1. Check that the Instrument is in SETUP and previous run data files saved and copied to an archive. +2. Then close SECI (`File Menu->Exit`). +3. Then to start IBEX Server, use the shortcut in the Windows start menu or run `start_ibex_server.bat` located in `c:\Instrument\Apps\EPICS`. This will close any open IBEX client windows. +4. To start IBEX client, click on the IBEX shortcut in the Windows start menu or the taskbar. + +### If IBEX is running and you want to start SECI: + +1. Check that the Instrument is in SETUP and previous run data files saved and copied to an archive. +2. Then run stop_ibex_server.bat which will either be a shortcut on the Windows Start menu, or you can browse with explorer to `c:\Instrument\Apps\EPICS` where it is located. This will close any open IBEX client windows as well. +3. Next browse to `c:\Program Files (x86)\STFC ISIS Facility\SECI` where `SECIUserInterface.exe` is located. Click on `SECIUserInterface.exe` to start SECI. + +## Post Switch Tasks + +- Check and, if necessary, update the RB number, username and run title - either IBEX or SECI may reset this back to what it was last time they were run. +- If you don't wish your next proper run to contain both IBEX and SECI sample environment data, do a short BEGIN/END to push this into a data file to discard. diff --git a/doc/obsolete/Using-Futurize.md b/doc/obsolete/Using-Futurize.md new file mode 100644 index 0000000..b651abc --- /dev/null +++ b/doc/obsolete/Using-Futurize.md @@ -0,0 +1,44 @@ +# Futurize + +:::{warning} +This guide is obsolete; scripts were migrated to Python 3 many years ago. +::: + +Futurize takes in your Python 2 code and turns it into valid Python 3 code, and also makes it backwards compatible with Python 2 using future package. + +## Using Futurize: +There are mainly two ways on how you can translate your script using Futurize. More information could be found [here](http://python-future.org/futurize_cheatsheet.html). + +### Translating a single file +* Open Command Prompt +* **cd** `C:\Instrument\Apps\Python\Scripts` +* **futurize** `path\to\your\script` + +Now it should suggest some changes, to overwrite your current file with the suggested changes run the following command. + +* **futurize -w** `path\to\your\script` + + +### Translating multiple files at once +You have to manually create a list of python scripts you want to translate and place them in a separate folder. Replace `path\to\your\recently\created\folder` with the name of the folder where you have bundled all your script. + +* Open Command Prompt +* `cd C:\Instrument\Apps\Python\Scripts` +* `futurize path\to\your\recently\created\folder -wno name_of_your_output_folder` + +`name_of_your_output_folder` = name of the folder where you want to save the output, does not require to be created beforehand. + +The output will be saved in `path\to\your\folder\name_of_your_output_folder` + +## Common Problems and troubleshooting: + +### Separating Unicode from bytes: +Python 2 str is equivalent to python 3 bytes and Python 2 Unicode is now Python 3's default string literal. Unicode in Python 2 is implicitly converted to bytes when it is being compared against bytes `b'123' == u'123` will result to `True` in Python 2 whereas in Python 3 this will result to `False`. + +### Division: +In Python 3, all divisions between int values will result into float. If you want an integer division/floor division '//' can be used in both python 2 and 3. + +## Additional Resources: +[More on Futurize](https://python-future.org/futurize.html) + +[Cheatsheet on writing Python2/3 compatible code](https://python-future.org/compatible_idioms.html) \ No newline at end of file diff --git a/doc/permanenet_run_control_setting.PNG b/doc/permanenet_run_control_setting.PNG new file mode 100644 index 0000000..9d49f89 Binary files /dev/null and b/doc/permanenet_run_control_setting.PNG differ diff --git a/doc/perspectives_moved_large.png b/doc/perspectives_moved_large.png new file mode 100644 index 0000000..38b1adc Binary files /dev/null and b/doc/perspectives_moved_large.png differ diff --git a/doc/script_generator/Downloading-and-Installing-The-IBEX-Script-Generator.md b/doc/script_generator/Downloading-and-Installing-The-IBEX-Script-Generator.md new file mode 100644 index 0000000..42ddbbc --- /dev/null +++ b/doc/script_generator/Downloading-and-Installing-The-IBEX-Script-Generator.md @@ -0,0 +1,7 @@ +# Downloading & Installing the IBEX Script Generator + +1. Visit https://github.com/ISISComputingGroup/ScriptGeneratorReleases/releases and from the latest release download the script_generator.zip file. +1. Unzip the script generator to the location you would like. +1. To launch the script generation open the folder you unzipped the script generator to and run the ibex-script-generator.exe + * You may have to enter admin privileges to complete the installation correctly +1. You may also want to create a shortcut and pin it to the taskbar. On instruments we should always do this to replace older versions of the script generator. diff --git a/doc/script_generator/Script-Generator-Customisation.md b/doc/script_generator/Script-Generator-Customisation.md new file mode 100644 index 0000000..31f8a3a --- /dev/null +++ b/doc/script_generator/Script-Generator-Customisation.md @@ -0,0 +1,5 @@ +# Script Generator customization + +## Want your script definitions to be loaded from or your scripts to be generated to a different place on the file system? + +We may be able to set that up for you if you are on an instrument. Please let us know at ISISExperimentControls@stfc.ac.uk \ No newline at end of file diff --git a/doc/script_generator/The-IBEX-Script-Generator.md b/doc/script_generator/The-IBEX-Script-Generator.md new file mode 100644 index 0000000..fd1c214 --- /dev/null +++ b/doc/script_generator/The-IBEX-Script-Generator.md @@ -0,0 +1,9 @@ +# The IBEX Script Generator + +## Downloading and installing + +Please see: [Downloading and Installing The IBEX Script Generator](Downloading-and-Installing-The-IBEX-Script-Generator) + +## Usage documentation + +Please see: [Script Generator](../Script-Generator) \ No newline at end of file diff --git a/doc/script_generator/Troubleshooting-the-Script-Generator.md b/doc/script_generator/Troubleshooting-the-Script-Generator.md new file mode 100644 index 0000000..1726153 --- /dev/null +++ b/doc/script_generator/Troubleshooting-the-Script-Generator.md @@ -0,0 +1,45 @@ +# Script Generator Troubleshooting + +## Cannot import inst + +When using the script generator not on an instrument the instrument scripts will not be available. This means we cannot import inst. + +Therefore we cannot use inst outside of the `run` function. Our suggestion is to `import inst` inside the run function and use it as normal in there: + +```python +def run(...): + import inst + inst.instrument_script_method() +``` + +## Warning: Could not load any script definitions from + +- The definitions have not been loaded into the correct place in the filesystem + - To fix simply move them into the location that is given in the warning message +- The place IBEX is looking for script definitions in the file + - See "Want your script definitions to be loaded from ...?" below +- It is possible the script definitions have errors in them + - The script generator will display a table detailing these errors if this is the case + - Please review your definitions keeping in mind the errors detailed in the table +- If it is none of these there is a chance it is because part of the script generator has crashed + - Please contact the IBEX team to see if it is a bug: see [How do I report a problem with IBEX?](https://github.com/ISISComputingGroup/ibex_user_manual/wiki/FAQ#id1) + +## Some of my script definitions have not loaded + +- The definitions may be placed in the wrong place + - Please place your definitions on the filesystem where your definitions are loaded from +- One of the locations where definitions are loaded from may be incorrect + - See "Want your script definitions to be loaded from ...?" below +- Some of the script definitions may have errors in the and so failed to load + - These errors will be displayed in a table in the script generator graphical user interface + - Please fix the script or ask the maintainer of the script to fix it + +## I get a blank screen where the script generator should be + +Please contact the IBEX team to see if it is a bug: see [How do I report a problem with IBEX?](https://github.com/ISISComputingGroup/ibex_user_manual/wiki/FAQ#id1) + +## My script generator never finished loading + +Please contact the IBEX team to see if it is a bug: see [How do I report a problem with IBEX?](https://github.com/ISISComputingGroup/ibex_user_manual/wiki/FAQ#id1) + +- One possible issue is that a dependency called git has not been loaded correctly. A workaround for this may be to install git separately to the script generator, please see https://git-scm.com/book/en/v2/Getting-Started-Installing-Git \ No newline at end of file diff --git a/doc/script_generator/UIScriptGenGenerated.JPG b/doc/script_generator/UIScriptGenGenerated.JPG new file mode 100644 index 0000000..c2f264f Binary files /dev/null and b/doc/script_generator/UIScriptGenGenerated.JPG differ diff --git a/doc/script_generator/Using-the-Script-Generator.md b/doc/script_generator/Using-the-Script-Generator.md new file mode 100644 index 0000000..7f607c9 --- /dev/null +++ b/doc/script_generator/Using-the-Script-Generator.md @@ -0,0 +1,100 @@ +# Using the Script Generator + +## Keyboard Shortcuts + +- Ctrl-click on multiple lines to select them all +- Tab onto the next cell (tabbing from the last cell creates a new line) + +## FAQ + +
+How do I copy and paste lines? +
+Select the line you want to copy (does not have to contiguous) and press `Ctrl+c` or use the "Copy Selected Actions" button to copy. Press `Ctrl+v` or use the "Paste Actions" button after selecting the line where you want to paste. +
+ +
+How do I delete multiple lines? +
+Select the lines individually (by holding `Ctrl` and clicking) or as a group (by holding `Shift` and clicking), then click the _Delete Selected Actions_ button or press the `Delete` key. + +To delete all lines, click the _Clear All Actions_ button or select all lines with `Ctrl+a` before deleting. +
+ +
+How do I insert an action at a given point? +
+Click the line you wish to insert the new line below and click the "Insert Action Below" button. +
+ +
+How do I add a new line to the end? +
+Click the "Add Action to End" button. +
+ +
+Can I tab between cells? +
+Yes, pressing tab to move between cells will move the focus from left to right and then onto the next line. If you tab off the end of the last line a new line will be created. +
+ +
+What does `Transfer Compatible Parameters` option do? +
+When this option is selected and the user selects a different script definition the actions are transferred if possible (i.e. when parameters match and they are not set to copy previous row). The matching parameters are transferred and the rest are populated with their default values. It is possible that none of the parameters can be transferred in which case the actions are cleared. +
+ +## A tour of the UI + +![ScriptGenerator UI](script_generator_ui.jpg) + +1. From the drop-down here you may select a script definitions to use to generate a script. +2. This text box displays the help provided by the currently selected script definition. +3. Help options, click the arrow to open a drop down allowing access to a link to this page and an about section which contains the current version, Java version, and the Java Path. +4. If the data entered in one of the global parameters text box is not the correct type it will highlight in red, mousing over the text box will display the error. +5. Text box to enter global parameters, these are only displayed if they are defined by the selected script definition. +6. This table may not appear in your script generator. However, if it does this means there have been errors loading some of your script definitions. The error message may tell you there is an error in one of your script definitions or there has been an error loading from a specific location. +7. The script generator table is to contain the experimental parameters that will be used by the generated script. +8. The validity column will contain a tick and be coloured green if the row is valid. +9. The validity column will contain a cross and be coloured a deeper red if the row is invalid. This is dependent on the script definitions parameters_valid method. +10. Hovering over a row that is invalid (highlighted in red and with a cross mark in the validation column) will display the reason this row is invalid. This is dependent on the script definitions parameters_valid method. +11. Select a row and press the up or down button to reorder rows. +12. Select an action or actions and click the "Copy selected actions" button to add the selected actions to the clipboard. +13. Select a row and click "Paste actions" to add the actions in the clipboard to the table. +14. Create a new action (row in the script generator table) at the bottom of the table with the "Add Action To End" button. +15. Select a row and click the "Insert Action Below" button to add a new action directly below the current action. +16. Select an action or actions and click the "Duplicate Selected Actions Below" button to create a copy of all currently selected actions directly below the last selected item. +17. Select an action or actions and click the "Delete Selected Actions" button to remove the selected actions from the table. +18. Click the "Clear All Actions" button to remove all actions from the table. +19. Click the "Generate Script" button to save out the script when all actions are ready. The button to generate a script is greyed out when the parameters aren't valid. +20. Click the "Save Parameters" button to save the current parameters to a file that can be loaded in at another time. The button to generate a script is greyed out when the parameters aren't valid. +21. Click the "Save Parameters As ..." button to save the current parameters to a file that can be loaded in at another time, specifying the file to save to rather than saving to the file last saved to or loaded. The button to generate a script is greyed out when the parameters aren't valid. +22. Click the "Load Parameters" button to load previously saved parameters in from a file. + +![](/script_generator/UIScriptGenGenerated.JPG) + +1. When all parameters are valid the get validity errors button is greyed out. +2. All parameters are valid when there are ticks in the validity columns and no rows are red. +3. Press the "Generate Script" button to generate a script from your experimental parameters and get a file message box pop up. +4. When the script has been generated in the backend a user can provide a filename (without file path prefix or file extension). + 1. They are provided with a create default filename which uses the script definition and a timestamp. +5. Can then save or save and open the file (at this stage if there is another file of the same name in the same place the user is asked if they want to overwrite). +6. Opens the file in notepad++ if notepad++ can be found. + + +![ScriptGenerator UI Success](UIScriptGenGenerated.JPG) +1. Press the "Generate Script" button to generate a script from your experimental parameters and get a file message box pop up. + - When the script has been generated in the backend a user can provide a filename (without file path prefix or file extension). + - They are provided with a create default filename which uses the script definition and a timestamp. + - Can then save or save and open the file (at this stage if there is another file of the same name in the same place the user is asked if they want to overwrite). +2. Opens the file in notepad++ if notepad++ can be found. +3. Do not open the file. +4. Estimated time for running of script, this is calculated based off the script definition. + + + + +## Loading scripts into the scripting window + +Say we have generated a script named "my_script.py". We can open the scripting perspective in the ibex gui and type `g.load_script("my_script.py")`. This will then load a function called `runscript()` into the console which you can call by simply typing `runscript()` and pressing enter. diff --git a/doc/script_generator/Writing-Script-Definitions.md b/doc/script_generator/Writing-Script-Definitions.md new file mode 100644 index 0000000..0decbff --- /dev/null +++ b/doc/script_generator/Writing-Script-Definitions.md @@ -0,0 +1,147 @@ +# Writing Script Definitions + +## ScriptDefinition + +For an example script definition see: [The ScriptDefinition Class (with Example)](https://isiscomputinggroup.github.io/ibex_developers_manual/script_generator/Script-generator-high-level-design.html#scriptgenerator-script-definition). A script definition is defined by creating a class implementing a ScriptDefinition (a python interface) `class DoRun(ScriptDefinition):`. ScriptDefinition must be imported before doing this so add at the top of your file `from genie_python.genie_script_generator import ScriptDefinition `. + +To implement an ScriptDefinition this DoRun class must have methods `run`, `parameters_valid` and `get_help`. With `run` and `parameters_valid` signatures may look like this: `def run(self, temp="1", field="1"):`, `def parameters_valid(self, temp="1", field="1"):`. + +Both `run` and `parameters_valid` methods must take the same arguments (in this case `temp="1", field="1"`) and must have the `self` argument first. All the arguments except self must have a default value in our example "1" is the defaults. All the arguments taken except for `self` are of type string, if you want to change this see "Casting Parameters" below. + +When defining a `get_help` method we are returning a string that we want to be displayed to the users in the script generator UI, for example: + +```python +def get_help(self): + return "My help string" +``` + +If we do not want to display a string to the user we return None: + + +```python +def get_help(self): + return None +``` + +Optionally a script definition can specify an `estimate_time` method, which will take the same arguments as `run` and `parameters_valid` and return a float giving an estimate of how long a script will take (in seconds). When defining this method we are returning how long each row in the script generator table will take to run. +```python + def estimate_time(self, field1="1", field2="2"): + return float(field1) * float(field2) +``` +In order for this method to perform arithmetic operations on scientific notations, it is mandatory to cast the argument as float for e.g. `float(field1)`. + +## Default values + +The initial value of an action in the table can be defined within your script definition. Simply set the default values of the run method and these will be converted into a string for the initial value in the table. + +Please note that the value you put as a default will be passed through any casters when running. So for example with our `magnet_device_type` caster below the valid inputs into the action table are LF, TF, ZF or N/A which are cast to Danfysik, T20, Active ZF and N/A. When defining the default you should use the valid inputs for the actions table e.g. LF, TF, ZF or N/A. + + +## Casting Parameters + +### cast_parameters_to + +This decorator allows you to cast the parameters you receive for your `run` and `parameters_valid` methods, for example: + +```python +@cast_parameters_to(temp=float, field=float) +def run(self, temp=1.0, float=1.0): +``` + +Here we pass temp a cast called float. This will call `float(temp)` on whatever is passed to `run` before `run` is called so you can treat temp as a floating-point number. If casting the input fails this will be propagated back up to the user. Other casters include int, long and hex. If there does not exist a caster that fits your specification you can write one yourself see "Custom Casters". + +### Custom Casters + +When float, int etc. are not enough you can define your own function to cast an input. These take one argument (the argument to cast) and return the casted value. See examples below for details. + +Say we want our users to be able to input a floating-point value for the temperature, but we also want them to be able to input the word "KEEP" or even "KeEp" to not change the value we can define the caster below: + +```python +def float_or_keep(temp): + if temp.lower() == "keep": + return None + else: + return float(temp) +``` + +Say we have a set of magnets that we are wanting the user to select in an argument (or no magnet "N/A") we can define the below caster: + +```python +magnet_devices = {"ZF": "Active ZF", "LF": "Danfysik", "TF": "T20 Coils"} + +# Convert to magnet device type if possible, if not they have input an incorrect magnet_device +# Raise a ValueError and this will be caught and displayed to the user that the conversion is incorrect +def magnet_device_type(magnet_device): + magnet_device = magnet_device.upper() + if magnet_device in magnet_devices.keys(): + return magnet_devices[magnet_device] + elif magnet_device == "N/A": + return magnet_device + raise ValueError("Magnet device must be one of {} or N/A".format(magnet_devices)) +``` + +To say we cannot cast the argument we raise a ValueError which tells cast_parameters_to that we have failed to cast the argument. The string you type into the ValueError (e.g. "Magnet device must be one of {} or N/A".format(magnet_devices)) will be propagated back up to the user. + +## Copying from previous rows + +`CopyPreviousRow` instances can be used to specify parameters in functions which should copy any previous row's value. This could be used to avoid re-specifying the values manually when creating a script. + +Usage: + +```python +from genie_python.genie_script_generator import ScriptDefinition, cast_parameters_to, CopyPreviousRow + +class DoRun(ScriptDefinition): + @cast_parameters_to(temperature=float_or_keep, field=float_or_keep, mevents=int, magnet_device=magnet_device_type) + def run(self, temperature=CopyPreviousRow(1.0), field=1.0, mevents=10, magnet_device="N/A"): + ... +``` + +The `temperature` field here would still have a default value of 1.0 if no actions exist, however if a user changes this value and adds another row it will be copied over to the next row. + +## Using python, genie and inst + +The script generator uses the python that we bundle with it which comes pre-installed with everything you would expect on an instrument (except inst) so you can easily write genie commands into your script definition etc. + +However, it does not come with installed instrument scripts that you obtain via inst. Due to this, if you try to import inst outside of your `run` method your script definition will produce errors for your users and fail to load when not on the instrument itself. Our suggestion is to import inst inside the run function and use it as normal in there: + +```python +def run(...): + import inst + inst.instrument_script_method() +``` + +## Global parameters + +In a script definition you can define a number of global parameters by creating an ordered dictionary field for your `DoRun` class named `global_params_definition` e.g. + +```python +class DoRun(ScriptDefinition): + + global_params_definition = OrderedDict({"example param:": ("0", int), "example param 2:": ("2", float), + "example param 3:": ("any string", str)}) +``` + +These global parameters can then be accessed in the `run`, `parameters_valid` and other methods by calling `self.global_params["example param 2:"]`. The global parameters will appear above the actions table in the user interface and can be set by the user. The set value is applied for the entirety of the script. + +### Validating global parameters + +You can provide a validation function for global parameters. For example with `"example param 2:": ("2", float)` if we want to force it to be between 1 and 3, we can change `float` to be a function say `param2_validator` which we define in our script definition: + +```python +from genie_python.genie_script_generator import ScriptDefinition, GlobalParamValidationError +from collections import OrderedDict + +def param2_validator(param2) : + param2 = float(param2) + if param2 < 1 or param2 > 3: + raise GlobalParamValidationError("Param 2 must be between 1 and 3") + return param2 + + +class DoRun(ScriptDefinition): + global_params_definition = OrderedDict({"example param:": ("1", int), "example param 2:": ("1.23", param2_validator), + "example param 3:": ("hello", str), "example param 4:": ("0", int)}) +``` + +When `example param 2` is then set in the script generator, it will be validated using `param2_validator`. \ No newline at end of file diff --git a/doc/script_generator/script_generator_ui.jpg b/doc/script_generator/script_generator_ui.jpg new file mode 100644 index 0000000..440833c Binary files /dev/null and b/doc/script_generator/script_generator_ui.jpg differ diff --git a/doc/scripting/Alerts-on-Blocks.md b/doc/scripting/Alerts-on-Blocks.md new file mode 100644 index 0000000..338ac56 --- /dev/null +++ b/doc/scripting/Alerts-on-Blocks.md @@ -0,0 +1,60 @@ +# Alerts on Blocks + +Alerts can be configured on blocks using genie python, there is no GUI for this at the moment. An alert will trigger when a block is outside of the specified `lowlimit,highlimit` range for the specified `delay_out` time, it is like run control but rather than putting the DAE into WAITING a message (via SMS text and/or email) is sent. When the value comes back in range, it must be in range for `delay_in` seconds until an in-range alert is sent. + +Note that this system is in addition to and independent of run control, it just uses some of the same underlying software. Alerts can be added to blocks that are not under run control, and both run control and alerts can bet set on the same block. The limits and delay times need not be the same for the run control and alert elements, so the instrument could be configured to go into a WAITING state when a block exceeded 100K but not send an alert until it exceeded 120K for a given length of time etc. (see below for how to set an alert on how long an instrument has been in a WAITING state) + +```python +## set mobiles and emails to send alerts to +## this is remembered and only needs to be repeated if values change +g.alerts.set_sms(["123456789", "987654321"]) +g.alerts.set_email(["a@b", "c@d"]) + +## set alert on block1 with default delay_in and delay_out (which is no delay) +## setting a range automatically enables the alert +g.alerts.set_range("block1", -10.0, 20.0) + +## set alert on block2 with specified delay_in and delay_out times +## if you have a block value that may temporarily spike, but you are only +## interested in sustained periods out of range, then specify a delay_out +## so that e.g. it must be out of range for at least 15 seconds to trigger +## an out of range alert and back in range for at least 5 seconds to trigger +## an in range alert +g.alerts.set_range("block2", -10.0, 20.0, delay_in=5.0, delay_out=15.0) + +## alerts can be separately enabled and disabled, any previous +## specified ranges and in/out delays are applied +g.alerts.enable("block1") # enable alerts on block1 +g.alerts.enable("block2", False) # disable alerts on block2 + +## print status of all configured alerts to screen +g.alerts.status() + +## test +g.cset("block1", -50) # With above settings, message sent to say the block has gone out of range +g.cset("block1", 0) # With above settings, message sent to say the block has gone back in range +``` +Alerts are saved across IBEX restarts, but the saving is not currently part of a configuration. The block related alert parameters will remain so long as the block exists (the ``email`` and ``sms`` parameters are always preserved), so you can change configuration and maintain an alert so long as the block continues to exists. If you change to a configuration where the block does not exist, then you lose those block specific alert settings. So it is best to create the blocks used for alerts as part of a common base component included in all configurations. + +Alerts, like run control, are normally set on floating point (or integer) value blocks. They can, however, be used on some "state" items that are symbolic names mapped to integers (enums). One example of this is the instrument state (SETUP=1,RUNNING=2,PAUSED=3,WAITING=4,VETOING=5) so if a block called `RunState` is attached to the process variable `IN:myinst:DAE:RUNSTATE` then +```python +g.alerts.set_range("RunState", -1.0, 3.5, delay_in=5.0, delay_out=300.0) +``` +will send an alert if the instrument has been WAITING or VETOING (>3.5) for more than 300 seconds. + +## Sending alert messages directly from scripts +You can also send an immediate alert message from an executing script by doing the following +```python +## set mobiles and emails to alert, these aren't required if the email/phone numbers +## have already been set at some other point on your instrument +g.alerts.set_sms(["123456789", "987654321"]) +g.alerts.set_email(["a@b", "c@d"]) + +if bad_thing_happened: + g.alerts.send("Help, a bad thing has happened!") +``` + +## Future enhancements +* Create GUI for managing alerts, similar to how run control is done now +* Allow saving alerts into a configuration/component + \ No newline at end of file diff --git a/doc/scripting/Block-names-helper.rst b/doc/scripting/Block-names-helper.rst new file mode 100644 index 0000000..298f00d --- /dev/null +++ b/doc/scripting/Block-names-helper.rst @@ -0,0 +1,31 @@ +Block Names Helper +################## + +There is a block name helper which can save you typing block names as strings and potentially making mistakes. This can be imported into your script or console with: + +.. code-block:: python + + from genie_python import BLOCK_NAMES as b + +usually as part of the genie import: + +.. code-block:: python + + from genie_python import genie as g, BLOCK_NAMES as b + +The typing `b.` will give you a list of current blocks; in the console you need to press tab. This can be used in place of a normal string in something like cget. For example + +.. code-block:: python + + from genie_python import genie as g, BLOCK_NAMES as b + + g.cset(b.TEMP, 10) + g.cget(b.TEMP) + g.show(b.TEMP) + +Advanced +-------- + +1. If the block asked for is not in the current configuration this will still returns the block name and in addition will print a warning. + +2. Python has a few keywords and these can not be used in the `b.` syntax. If you have a block called this it will be replaced by the same name suffixed with two underscores. For example a block called `while` would be referred to be `b.while__`. diff --git a/doc/scripting/Creating-and-Running-Scripts.rst b/doc/scripting/Creating-and-Running-Scripts.rst new file mode 100644 index 0000000..10c96c1 --- /dev/null +++ b/doc/scripting/Creating-and-Running-Scripts.rst @@ -0,0 +1,150 @@ +Creating & Running Scripts +########################## + +Types of Scripts +================ + +- `Creating and running instrument + scripts <#creating-and-running-instrument-scripts>`__ +- `Creating and running user + scripts <#creating-and-running-user-scripts>`__ + +Creating and running instrument scripts +======================================= + +Different instruments may have specific scripts that are required for +multiple users. To make accessing these easier, ``genie_python`` loads +instrument scripts at startup. + +Creating scripts +---------------- + +For the most part, this is the same as +`creating-user-scripts <#creating-and-running-user-scripts>`__. + +Script module +~~~~~~~~~~~~~~~~ + +For instruments where a single file is sufficient, instrument scripts should be placed in ``C:\Instrument\Settings\config\[MACHINE_NAME]\Python\inst.py``. + +For instruments with complex scripts which need more than one file, you should put your scripts in the inst folder, for example ``C:\Instrument\Settings\config\[MACHINE_NAME]\Python\inst\my_functions.py``. + +When using a multi-file ``inst`` module, to make the functions available under the ``inst`` namespace as ``inst.do_thing()`` as opposed to ``inst.my_functions.do_thing()``, you will need to add the special file ``__init__.py``. Anything which is imported into this file (using normal python ``import`` statements) will be available under the ``inst`` namespace. + +Script structure +~~~~~~~~~~~~~~~~ + +Everything in the instrument scripts will be executed when +``genie_python`` is started. This includes - Making functions available +to be called later - Setting variables - Running methods. Typically, most +code in instrument scripts will be contained within functions +(procedures in Open GENIE language), but it's important to be aware that +anything that isn't will be included too. For example, if an instrument +script is loaded: + +:: + + a = 1 + def print_a(): + print str(a) + +then the user can call ``print_a``, but they can also use the variable +``a``, and change its value, which may not be desirable. If instead the +script was: + +:: + + def print_a(): + a = 1 + print str(a) + +then the user could only access ``print_a()`` and the value could not be +changed. + +To reload the inst module, for instance if you had updated the script or added a new script, you should issue the command ``reload(inst)``. + +Running +------- + +**Please note:** When you are running scripts, the script is being executed on the instrument control PC. This means that the script itself has to be stored on the instrument control PC. It also means that any path names in your scripts refer to locations on the instrument control PC (unless you are referring to network drives). + +Once the script is loaded, anything from the script will be available +using the ``inst`` package reference. For instance if your script +contains the function ``my_function`` you can call: + +:: + + inst.my_function() + +Whilst using the scripting perspective in the IBEX GUI, users will also +benefit from the same auto-complete feature as they do with +``genie_python`` commands. + +Creating and running user scripts +================================= + +Creating scripts +---------------- + +1. First, we need to create a script file. By default, user scripts + should be placed in ``C:\scripts``. Navigate to your desired + directory and create the script file with extension ``.py``. +2. Write some ``genie_python``! +3. Save the file + +We have glossed over step 2 because Python is a very powerful scripting +language. Combined with Open GENIE, the potential scope of a script is +enormous, and well beyond the scope of this guide. For example though, +here is a simple script that executes a calibration run. + +:: + + from genie_python import genie as g, BLOCK_NAMES as b + + # Change the title + calibration_run_title = "Calibration run 1, 29th September" + g.change(title=calibration_run_title) + + # Begin the run + print "Beginning calibration run : " + calibration_run_title + g.begin() + + # Wait for 100 uamps + g.waitfor(uamps=100) + + # End the run + g.end() + print "Calibration run finished successfully" + +Running +------- + +**Please note:** When you are running scripts, the script is being executed on the instrument control PC. This means that the script itself has to be stored on the instrument control PC. It also means that any path names in your scripts refer to locations on the instrument control PC (unless you are referring to network drives). + +Once you've created your script, it's time to run it. There are a number +of ways of launching a Python script. + +From IBEX +~~~~~~~~~ + +1. Launch the IBEX GUI +2. Navigate to the scripting perspective +3. Run the command ``g.load_script("C:\path\to\script\my_script.py")`` + where the path and script name are updated appropriately + + - Note that if you omit the absolute path to the file (i.e. + ``C:\path\to\script``) then ``genie_python`` will look in the + current script directory. By default this is ``C:\scripts`` but + can be viewed and set with the commands ``g.get_script_dir()`` and + ``g.set_script_dir()`` respectively. + +4. When the script is loaded, any procedures in the script will be run + automatically. If the script contains any function, you will now be + able to call them from within the scripting window. + +From a genie\_python terminal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Launch a ``genie_python`` terminal from + ``C:\Instrument\Apps\Python\`` by running ``genie_python.bat`` +2. Follow the above starting at step 3. \ No newline at end of file diff --git a/doc/scripting/Error-Checking-Troubleshooting.rst b/doc/scripting/Error-Checking-Troubleshooting.rst new file mode 100644 index 0000000..53f6a5a --- /dev/null +++ b/doc/scripting/Error-Checking-Troubleshooting.rst @@ -0,0 +1,195 @@ +Error Checking Troubleshooting +############################## + +====== +Pylint +====== + +Scripts are now “linted” on load, which means they are checked for validity against a variety of conditions. This means that more mistakes in the code can be caught before the script is run. The script is linted on load and if there are issues the output from `g.load_script` will look something like: + +.. code-block:: + + W: 2: Found indentation with tabs instead of spaces (mixed-indentation) + E: 4: Unable to import 'my_file_in_inst' (import-error) + +Where the initial *W:* indicates a warning or *E:* indicates an error and the number is the line number in the script. + +If loading a script produces warnings only, it will still be loaded successfully and can be used thereafter, whereas any errors will prevent a script from being loaded altogether. + +We do provide the option to disable linting by setting the check_script argument to false, i.e.: + +.. code-block:: python + + g.load_script("some_script.py", check_script=False) + +However, doing this is at your own discretion and with the understanding that you are exposing yourself to issues, either immediately or further down the line. We recommend fixing issues in scripts before running it. + +We have found that there are some common warnings and errors which we have listed below with suggestions of what might be wrong. If you find something that is not included let us know and we can add it to this page to help others. + +Errors +------ + +**Unable to import 'file_in_inst' (import-error)** + +This happens when the script contains something like + +.. code-block:: python + + from file_in_inst import my_function + +where *file_in_inst* is a file in your *NDX/Python/inst* directory, such as *inst_routines* +This may work at the command line but does not work with the checker/linter. A better way of writing this is + +.. code-block:: python + + from inst.file_in_inst import my_function + +The checker does not know of this special case of allowing `inst` modules on the command line unprefixed. + +**Undefined variable `g` or `inst`** + +You need to add the following lines to the top of your user script: + +.. code-block:: python + + from genie_python import genie as g + import inst + +This is so that the linter knows what is being referenced when you call functions on the g or inst modules. + +**Undefined variable ...** + +If is a genie_python or instrument script function that you are trying to use then there are two options. + +You can add the following lines to the top of your script: + +.. code-block:: python + + from genie_python import genie as g + import inst + +You will then need to replace with g. or inst. in your script. + +Alternatively import the functions directly: + +.. code-block:: python + + from genie_python.genie import + from inst import + + +Warnings +-------- + +**Found indentation with tabs instead of spaces (mixed-indentation)** + +Here the script file you are loading contains both spaces and tabs. This can upset the python interpreter although this is usually caught on import; we recommend using spaces for indent. + +If you are using Notepad++ as your editor it can be made to use spaces instead of tabs when you press tab. This is done by + +#. Select from the menu bar Settings -> Preferences. +#. Select Language in the left-hand box +#. In "Tab Settings" box select "python" +#. Untick "Use default value" and tick "Replace by space". + +**Unused import XXXX from wildcard import (unused-wildcard-import)** + +Although wildcard imports are not recommended because of the possibility of name collisions if you want to use it the linter will give you lots of warning about anything you didn't use from the package. To disable these warnings place the following comment on the import line which will suppress these warnings: + +.. code-block:: python + + from XXXX import * # pylint: disable=unused-wildcard-import + +You will still get a warning about wildcards which is good but not the warning about unused methods. + +============ +New: Pyright +============ + +As well as being 'linted', scripts are now checked against Pyright on load. This means that there will be fewer errors during runtime, as they will be caught when the script is being loaded. This is beneficial as it means that if your script has an inherent problem that could affect your equipment and you try to load and run it, it is more likely now that IBEX will not let your script be run. However, this may also mean that scripts that once worked may not anymore. + +Why Pyright? +------------ + +Pyright is a static type checker for Python. It helps ensure that your code is type-safe and adheres to the type annotations you’ve provided. By integrating Pyright into the script checking process, we aim to catch more errors at the time of script loading, reducing the likelihood of runtime errors that could cause issues with your equipment or experiments. + +Implications for Current and Future Scripts +------------------------------------------- + +Current Scripts: Scripts that previously loaded without errors may now produce errors due to type inconsistencies or other issues that Pyright detects. These scripts will need to be updated to resolve these issues before they can be loaded and run successfully. +Future Scripts: When writing new scripts, it is good to pay closer attention to adding type annotations. This will help avoid errors when the script is loaded. Note that Pyright errors will take the same format as the previously mentioned Pylint errors, but will be preceded by a [PR] representing Pyright. +Examples of Common Pyright Errors +Here are some examples of scripts that may not have produced load-time errors before but will now do so due to Pyright's checks. + +**Example 1: Invalid Range** + +.. code-block:: python + + def wrong(): + for i in range(1, 3.5): # Invalid range. Upper bound should be an integer. + print(i) + +*[PR] E: 2: Argument of type "float" cannot be assigned to parameter "stop" of type "SupportsIndex" in function "__new__"* + +**Example 2: Incompatible Type Assignment** + +.. code-block:: python + + c: int | float = 3.4 # Python is being told c is either an int or a float of value 3.4. + c = None # c is defined as nothing. So Pyright throws error. + +*[PR] E: 2: Expression of type "None" is incompatible with declared type "int | float"* + +**Example 3: Incorrect Argument Types** + +.. code-block:: python + + from genie_python import genie as g + def wrong(): + g.begin(1,2,3,4,5,6,7,8,9) # Correct number of arguments but of wrong type. + +*[PR] E: 3: Argument of type "Literal[3]" cannot be assigned to parameter "meas_type" of type "str" ...* + +Using Type Annotations +---------------------- + +Type annotations in Python allow you to explicitly declare the expected data types of variables, function arguments, and return values. This helps in catching type-related errors early and improves the readability and maintainability of your code. Here’s a brief guide on how to use type annotations effectively: + +Function Arguments and Return Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify the types of function arguments and return values using type hints. + +.. code-block:: python + + def greet(name: str) -> str: + return f"Hello, {name}!" + +In this example: + +- ``name: str`` indicates that the name parameter should be of type str (string). +- ``-> str`` indicates that the function returns a str. + +Complex Types +~~~~~~~~~~~~~~ +For more complex types, such as lists, dictionaries, or custom objects, you can use annotations from the typing module. + +.. code-block:: python + + from typing import List, Dict + + numbers: List[int] = [1, 2, 3, 4] + person: Dict[str, int] = {"age": 30, "height": 175} + +In this example: + +- *numbers* is annotated as a list of integers ``List[int]``. +- *person* is annotated as a dictionary with string keys and integer values ``Dict[str, int]``. + +============================================== +What do I do if I can't fix my Pyright error?? +============================================== + +> If it is just the one line that is causing an issue then you can always write a "# type: ignore" at the end of the line to have it ignored by Pyright. + +> If all else fails, when you make a call to ``g.load_script('script.py')``, you can add a second argument to disable linting and type checking as follows: ``g.load_script('script.py', check_script=False)`` \ No newline at end of file diff --git a/doc/scripting/Genie-Python-Training.md b/doc/scripting/Genie-Python-Training.md new file mode 100644 index 0000000..327a69c --- /dev/null +++ b/doc/scripting/Genie-Python-Training.md @@ -0,0 +1,15 @@ +# Genie Python Training Course + +```{toctree} +:maxdepth: 1 +:titlesonly: +:glob: + +training_course/genie_python-and-IBEX-(Introduction) +training_course/genie_python-and-IBEX-(Getting-started) +training_course/genie_python-and-IBEX-(Common-commands) +training_course/genie_python-and-IBEX-(Scripting) +training_course/genie_python-and-IBEX-(Converting-from-Open-GENIE) +training_course/genie_python-and-IBEX-(Closing-remarks) +training_course/genie_python-and-IBEX-(Exercise-solutions) +``` diff --git a/doc/scripting/Matplotlib.md b/doc/scripting/Matplotlib.md new file mode 100644 index 0000000..1fada6e --- /dev/null +++ b/doc/scripting/Matplotlib.md @@ -0,0 +1,101 @@ +# Matplotlib + +The python distribution deployed on instruments includes a powerful plotting library called {external+matplotlib:py:mod}`matplotlib`. + +Matplotlib is a highly customisable, general purpose plotting library capable of producing a wide variety of plot types. There are lots of tutorials and examples online, such as: +- {external+matplotlib:ref}`Matplotlib tutorials ` +- {external+matplotlib:ref}`Matplotlib examples ` +- {external+matplotlib:py:mod}`matplotlib.pyplot` command reference + +```{contents} +``` + +## Import pyplot + +The most user-friendly interface to matplotlib is called {external+matplotlib:py:mod}`matplotlib.pyplot`. You can import {external+matplotlib:py:mod}`pyplot ` using the following command: + +```python +import matplotlib.pyplot as pyplot +``` + +## Useful pyplot commands +- {external+matplotlib:py:obj}`matplotlib.pyplot.plot`: Populate a plot with some data. +- {external+matplotlib:py:obj}`matplotlib.pyplot.clf`: Clear the current figure, e.g. discard old data from the plot. +- {external+matplotlib:py:obj}`matplotlib.pyplot.show`: Shows the matplotlib plotting window. +- {external+matplotlib:py:obj}`matplotlib.pyplot.draw`: Draws updates to a plot that is already open. +- {external+matplotlib:py:obj}`matplotlib.pyplot.close`: Closes plots and removes all data. +- {external+matplotlib:py:obj}`matplotlib.pyplot.figure`: Creates or switches to figure n. + + +## Example: plot and show a trivial graph +```python +import matplotlib.pyplot as pyplot +pyplot.plot(range(10)) +pyplot.show() +``` + +## Example: plot a constantly-updating sin wave +```python +import matplotlib.pyplot as pyplot +from math import sin +from time import time, sleep + +# Create a new figure. +pyplot.figure() + +# Show plot - only need to do this once,! (this will display the blank figure) +pyplot.show() + +while True: + # Clear the old data from the figure - we want to replace it completely. + pyplot.clf() + # Plot our new data onto the figure. + pyplot.plot([sin(x/1000.0 + time()) for x in range(10000)]) + # Draw the new data to the screen. + pyplot.draw() + # Short sleep to avoid going into a tight loop and using 100% processor. + sleep(0.5) +``` + +## Plotting spectra + +The `genie_python` library includes commands to plot the neutron spectra on an instrument quickly. + +Plot a single spectrum: +```python +g.plot_spectrum(1) +``` + +Plot several spectra on one graph: +```python +graph = g.plot_spectrum(1) +graph.add_spectrum(2) +graph.add_spectrum(3, period=2) +``` + +Plot several spectra on different graphs: +```python +g.plot_spectrum(1) +g.plot_spectrum(2) +``` + +For greater control over the exact presentation or contents of the spectra plots, the raw spectrum data can be acquired using: +```python +g.get_spectrum(spectrum=1) +``` + +## Using matplotlib within the IBEX GUI + +The IBEX user interface includes a python scripting window. When plotting graphs within IBEX, matplotlib is configured to display the plot within the IBEX gui. + +In the IBEX user interface, matplotlib is _non-blocking_ - that is, a script will continue once a plot has been drawn without the plot needing to be closed. + +:::{note} +This is new functionality as of July 2018. If you prefer matplotlib windows to spawn separately from the main IBEX window, you can type the matplotlib command: +```python +matplotlib.use('Qt4Agg') +``` +This needs to be typed before any matplotlib functionality is used for it to take effect. +::: + +By default, only 3 plots can be opened at a time. If this limit is exceeded, the oldest plot will be automatically removed. \ No newline at end of file diff --git a/doc/scripting/OpenTheScriptingPerspective.png b/doc/scripting/OpenTheScriptingPerspective.png new file mode 100644 index 0000000..f46a3f1 Binary files /dev/null and b/doc/scripting/OpenTheScriptingPerspective.png differ diff --git a/doc/scripting/Pre-and-Post-Command-Hooks.md b/doc/scripting/Pre-and-Post-Command-Hooks.md new file mode 100644 index 0000000..c149c38 --- /dev/null +++ b/doc/scripting/Pre-and-Post-Command-Hooks.md @@ -0,0 +1,32 @@ +# Pre & Post-command Hooks + +It is possible to hook in functions that run pre and post the execution of some genie commands (begin, end, abort, pause, resume). + +This is done passing functions to genie python setter commands. There are setter commands for begin, end, abort, pause and resume (func is the function you wish to run before or after the command): + +- {external+genie_python:py:obj}`genie_advanced.set_begin_precmd` + - This has a special case where the function returns None to say that after the function we should execute begin. + - If anything else is returned the run does not begin but a string representation of whatever is returned will be printed to the user. A possible use of this is returning a string saying "Run already in progress, continuing run". +- {external+genie_python:py:obj}`genie_advanced.set_begin_postcmd` +- {external+genie_python:py:obj}`genie_advanced.set_end_precmd` +- {external+genie_python:py:obj}`genie_advanced.set_end_postcmd` +- {external+genie_python:py:obj}`genie_advanced.set_abort_precmd` +- {external+genie_python:py:obj}`genie_advanced.set_abort_postcmd` +- {external+genie_python:py:obj}`genie_advanced.set_pause_precmd` +- {external+genie_python:py:obj}`genie_advanced.set_pause_postcmd` +- {external+genie_python:py:obj}`genie_advanced.set_resume_precmd` +- {external+genie_python:py:obj}`genie_advanced.set_resume_postcmd` + +You only ever need to call the `set__<>cmd(func)` once and func will then always be called for subsequent RUN_ACTIONs. + +An example of usage would be: + +```python +>>> def before_begin_func(**pars): +... print("About to begin!!") +>>> +>>> set_begin_pre_cmd(before_begin_func) # Note the lack of brackets on before_begin_func here +>>> begin() +About to begin!! +** Beginning Run... +``` diff --git a/doc/scripting/Simulating-Scripts.md b/doc/scripting/Simulating-Scripts.md new file mode 100644 index 0000000..9ab3488 --- /dev/null +++ b/doc/scripting/Simulating-Scripts.md @@ -0,0 +1,103 @@ +# Simulating Scripts + +## Simulated Genie Python + +Before running a script on real hardware you may want to check that the script will behave as expected and contains no errors. To help do this `genie_python` has a simulated mode where commands that would normally communicate with hardware instead print what they are doing. To get in and out of simulation mode there is a [context manager](https://www.geeksforgeeks.org/context-manager-in-python/) which will turn simulation mode on only for the code inside it's scope and will then turn it off for you after. This can be used like: + +```python +with g.sim.Simulate(): + g.begin() + g.cset("Freq_T0", 10) + print(g.cget("Freq_T0")) + g.end() +``` +which would give: +``` +Run started +Waiting to exit state SETUP +Setting Freq_T0 to value 10 +OrderedDict([('connected', True), ('name', 'Freq_T0'), ('value', 10), ('runcontrol', None), ('lowlimit', None), ('highlimit', None), ('alarm', 'NO_ALARM')]) +Run ended +Waiting for state SETUP +``` + +This can also be used to run your own functions, e.g. +```python +g.load_script("my_script.py") +with g.sim.Simulate(): + my_function() # Any genie_python calls in here will be simulated +``` + +By default the simulation environment will be populated with all the current blocks that you have in your configuration and will give you errors if the script you are simulating tries to access blocks that do not exist in the current config. + +Within your scripts you can check if you are in simulation mode or not using `g.sim.in_sim_mode()` e.g. + +```python +with g.sim.Simulate(): + print(g.sim.in_sim_mode()) +print(g.sim.in_sim_mode()) +``` +``` +True +False +``` + +## Initial Block Values in simulation mode + +By default when entering simulation mode all blocks have the value `INITIAL_VALUE`. However, you may want to provide some defaults of your own so that you can simulate how the script will run from various starting conditions. You can do this by providing a dictionary of values when creating the context manager e.g.: + +```python +with g.sim.Simulate(initial_block_values={'TEST_BLOCK': 42.42}): + test_block_data = g.cget("TEST_BLOCK") + print(test_block_data['value']) +``` +``` +42.42 +``` + +You could also provide the current state of the instrument by using `cgets` before starting simulation mode: + +```python +current_block_values = {"TEST_BLOCK": g.cget("TEST_BLOCK")} +with g.sim.Simulate(initial_block_values=current_block_values): + ... +``` + +## What is and is not simulated + +Simulation mode **will only simulate the functions inside genie_python**, i.e. those beginning with `g.` e.g. `g.cset`, `g.cget` etc. It will **not** simulate the following: +* Anything deeper inside genie_python e.g. `g.os.open` +* Anything outside of `g.` e.g. `time.sleep()` + +There is some logic in simulation mode in that if you do `g.cset("my_block", 10)` followed by `g.cget("my_block")` the new value of the block will be 10. However, this is very limited and is a work in progress, if there are additional behaviours you would like to see in simulation mode please get in touch. + +The following are some examples of potential mistakes that could be made with simulation mode and some examples of how to fix them: + +```python +import matplotlib.pyplot as pyplot +from time import sleep +block_values = [] +while(True): + block_values.append(g.cget("my_block")["value"]) + sleep(10) # This will still wait for 10 seconds even when simulating!! + if my_block_value > 100: # The simulated value of my_block may never reach 100 and so this may loop forever + break +pyplot.plot(my_block_value) +pyplot.show() # This will still show a plot even when simulating!! +``` + +this could be improved by: + +```python +import matplotlib.pyplot as pyplot +from time import sleep +block_values = [] +while(True): + block_values.append(g.cget("my_block")["value"]) + g.waitfor_time(seconds=10) # Simulated genie_python will skip the wait here and just print + if my_block_value > 100 or g.sim.in_sim_mode(): # We will now stop looping if in simulation mode + break +if not g.sim.in_sim_mode(): # This will now only plot if not in simulation + pyplot.plot(my_block_value) + pyplot.show() +``` \ No newline at end of file diff --git a/doc/scripting/The-Scripting-Console.md b/doc/scripting/The-Scripting-Console.md new file mode 100644 index 0000000..58a0d79 --- /dev/null +++ b/doc/scripting/The-Scripting-Console.md @@ -0,0 +1,39 @@ +# The Scripting Console + +Genie python can be used inside the IBEX client by using the scripting console. To start this press the scripting button in the sidebar: + +![Toolbar](OpenTheScriptingPerspective.png) + +## Command History + +This console will let you type genie commands. Pressing Up/Down arrow keys lets you cycle through previous commands, filtered by what you have started typing into the prompt. + +Additionally, pressing "Page Up" will display a window containing the entire command history. Previous commands can be selected from the list or searched for using the text box at the bottom. If you want to search for terms anywhere inside the command (not just at the start), you can do this by prefixing the search term with the * symbol ("match anything"). So the search term `H20` will not match the command `g.load_script("H2O.py")`, but `*H20` will. + +Note that the command history is cleared when the IBEX client is restarted, but will be preserved when just the scripting console is restarted. + +## Toolbar + +The toolbar in the top right provides additional functionality. + +![Toolbar](TheScriptingPerspectiveToolbar.png) + +From left to right these buttons do the following: + +1. Stop the whole console. This will stop the current script and remove the console from view, useful if you are running multiple consoles. +1. Save the text that's in the console to file. +1. Stop the currently running script. This is useful if you realise that the script is doing something wrong. (This can also be done by pressing Ctrl+C) +1. Clear the console. This will remove all the text from the window, be careful though as this WON'T stop the current script. +1. Pin the console. This is not used. +1. Switch to a different console. This will be greyed out if you only have one console running. +1. Start a new console or a new view. You can use this to start a new console by selecting PyDev Console -> Python Console -> Ok. Be careful! Having multiple consoles running can lead to different consoles 'fighting' for control of the instrument. + +## Console Memory + +As of September 2019, there is a limit on the amount of output that can be kept in the console. This limit is enforced to prevent a long output log from claiming too much memory and slowing down the rest of the control system. + +The console output can also be manually saved & cleared by using the right-click console context menu. + +## Search Console + +You can search console text by right-clicking on the console, clicking "Find/Replace...", typing your search query in the "Find:" text field and pressing the "Find" button. \ No newline at end of file diff --git a/doc/scripting/TheScriptingPerspectiveToolbar.png b/doc/scripting/TheScriptingPerspectiveToolbar.png new file mode 100644 index 0000000..2eaf3a1 Binary files /dev/null and b/doc/scripting/TheScriptingPerspectiveToolbar.png differ diff --git a/doc/scripting/Tips-and-Examples.rst b/doc/scripting/Tips-and-Examples.rst new file mode 100644 index 0000000..84beaf4 --- /dev/null +++ b/doc/scripting/Tips-and-Examples.rst @@ -0,0 +1,121 @@ +Tips & Examples +############### + +Tips from the developers +======================== + +Even with correct syntax, a working script can become bug-prone and difficult for users to update. Here we document some tips +to help keep your scripts working as expected and easy to modify in the future. + +Argument ordering +----------------- + +As this is Python, ``genie_python`` conforms to the standard pattern of +calling Python functions. The arguments to the function are contained +within brackets and the variables passed in as a comma-separated list. +Ordering is important but can be overridden by using named variables, +for instance the following are all correct and equivalent: + +:: + + g.change_beamline_pars("PAR1",1) + g.change_beamline_pars(name="PAR1",value=1) + g.change_beamline_pars(value=1,name="PAR1") + g.change_beamline_pars("PAR1",value=1) + +In the last example, named and unnamed variables are mixed. Unnamed +variables must precede named variables. The following examples are not +valid + +:: + + g.change_beamline_pars(name="PAR1",1) # Named variable before unnamed + g.change_beamline_pars(1,"PAR1") # Cannot change order of unnamed variables + +Using named variables can be **very useful in avoiding mistakes**. For +instance, getting the order of high and low limits the wrong way round. +For instance this example: + +:: + + g.change_monitor(1,10,0) + +is wrong and wouldn't work. Instead, we could have written: + +:: + + g.change_monitor(1,high=10,low=0) + +which would have worked and makes it clear for whoever comes to edit the +code in future (hint: that person might be you!). + +Making Errors Standout in Python Console +---------------------------------------- + +Python console will display most output in black this is from the standard out but will display error information in red. Error information should be written to standard error using `sys.stderr.write("error\n")`. + +Some examples +======================== + +Sequentially sets a position (e.g. sample changer) and waits for a fixed number of uamps + +:: + + + from genie_python import genie as g, BLOCK_NAMES as b + + def loop_over_samples(block_name, position_names, charge_to_wait_for): + """ + Begins a run. Loops over a set of sample positions. Ends the run + + :param block_name: The name of the block containing the sample position + :param position_names: A collection of the positions to loop over + :param uamps_to_wait_for: The number of uamps to wait for between samples + """ + g.begin() + total_charge_to_wait_for = 0 + for position_name in position_names: + print("Moving sample changer to position: {0}".format(position_name)) + g.cset(block_name, position_name) + total_charge_to_wait_for += charge_to_wait_for + g.waitfor_uamps(total_charge_to_wait_for) + g.end() + +Reads the value of a block and moves it through a series of intervals to a new values taking a fixed time + +:: + + from genie_python import genie as g, BLOCK_NAMES as b + + def ramp(time, block_name, steps=100, final_value=0.0): + """ + Moves a block between an initial and target value over a sequence of steps, waiting a fixed time at each step. + + :param time: The overall time to take to ramp. Time will be split evenly between steps + :param nsteps: The number of steps to take during the ramp + :param block_name: The name of the block whose value to set + :param final_value: The value we want to ramp to + """ + + initial_value = g.cget(block_name)['value'] + if initial_value is None: + print("Unable to determine temperature from block {0}. No action will be taken".format(block_name)) + return + + def values_match(v1, v2): + tolerance = 0.001 + small = 1.0e-20 + return 2*abs(v1-v2)/(abs(v1)+abs(v2)+small) < tolerance + + step_duration = time/steps + for i in range(1, steps+1): + step_value = initial_value + (final_value - initial_value)/steps*i + g.cset(block_name, step_value) + print("Ramping to: {0} Target value: {1}".format(step_value, final_value)) + g.waitfor_time(seconds=step_duration) + new_block_value = g.cget(block_name)['value'] + if not values_match(new_block_value, step_value): + print("WARNING: The current value for block {0}, {1}, does not match the target value of {2}".format(block_name, new_block_value, step_value)) + + print("Ramp complete") + \ No newline at end of file diff --git a/doc/scripting/genie_python-Commands.rst b/doc/scripting/genie_python-Commands.rst new file mode 100644 index 0000000..aad749e --- /dev/null +++ b/doc/scripting/genie_python-Commands.rst @@ -0,0 +1,114 @@ +Genie Python Commands +##################### + +Running genie\_python commands +============================== + +When running ``python`` from an interactive console such as from +the GUI or after running ``C:\Instrument\Apps\Python3\genie_python.bat``, +the ``genie`` module will be aliased to ``g``. Genie commands can then +be accessed by using the prefix ``g.[COMMAND_NAME]``. For example: + +.. code-block:: python + + g.begin() + g.cset("BLOCK_1",1) + g.abort() + +This is particularly useful from the GUI which will auto-complete +commands and provide tool tips describing each function and its +arguments. + +Note that in many cases, arguments will be optional. For instance, +``begin`` can be used as ``g.begin()`` despite supporting all of the +arguments ``period``, ``meas_id``, ``meas_type``, ``meas_subid``, +``sample_id``, ``delayed``, ``quiet``, ``paused``, and ``verbose``. + +Running in simulation mode +-------------------------- + +Genie_python can be used in simulation mode. Simulation mode will allow you to run scripts but without changing items on your instrument. It does this by putting dummy commands in for some genie command, it also creates dummy blocks on the fly so that block values can be read and written to. **N.B.** This means that simulation can not be this will not validate your block names within the script. To run in simulation mode use the ``genie_python_simulate.bat`` found in ``C:\Instrument\Apps\Python3``. + +Common genie\_python commands +============================= + +Many ``genie_python`` commands share the same name with their Open GENIE +equivalent so it will often be very straightforward to find the function +you're looking for. Still, here is a list of the most commonly used +``genie_python`` commands. This is **not a complete list**. For full +information, consult the `genie\_python reference manual`_. + + +Starting and stopping a run +--------------------------- + ++-----------+----------------------------------------------------+--------------+ +| Command | Description | Example | ++===========+====================================================+==============+ +| begin | Starts a new run | g.begin() | ++-----------+----------------------------------------------------+--------------+ +| end | Ends the current run | g.end() | ++-----------+----------------------------------------------------+--------------+ +| abort | Aborts the current run | g.abort() | ++-----------+----------------------------------------------------+--------------+ +| pause | Pauses the current run | g.pause() | ++-----------+----------------------------------------------------+--------------+ +| resume | Resumes the current run after it has been paused | g.resume() | ++-----------+----------------------------------------------------+--------------+ + +Updating blocks and PVs +----------------------- + ++-----------+--------------------------------------------------------+-------------------------------------------+ +| Command | Description | Example | ++===========+========================================================+===========================================+ +| cget | Gets the useful values associated with a block | g.cget("NEW\_BLOCK") | ++-----------+--------------------------------------------------------+-------------------------------------------+ +| cset | Sets the setpoint and runcontrol settings for blocks | g.cset("NEW\_BLOCK",1) | ++-----------+--------------------------------------------------------+-------------------------------------------+ +| get\_pv | Gets the value for the specified PV | g.get\_pv("IN:INSTNAME:IOC\_01:STAT") | ++-----------+--------------------------------------------------------+-------------------------------------------+ +| set\_pv | Sets the value for the specified PV | g.set\_pv("IN:INSTNAME:IOC\_01:STAT",1) | ++-----------+--------------------------------------------------------+-------------------------------------------+ + +Run control +----------- + ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| Command | Description | Example | ++=====================+=========================================================================================+====================================+ +| get\_uamps | Gets the current number of micro-amp hours | g.get\_uamps() | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| get\_frames | Gets the current number of good frames | g.get\_frames() | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| get\_runstate | Gets the current status of the instrument as a string | g.get\_runstate() | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| get\_mevents | Gets the total counts for all the detectors | g.get\_mevents() | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| get\_totalcounts | Gets the total counts for the current run | g.get\_totalcounts() | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| waitfor | Waits until certain conditions are met | g.waitfor("NEW\_BLOCK",value=1) | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| waitfor\_block | Waits until block reaches specific value | g.waitfor\_block("NEW\_BLOCK",1) | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| waitfor\_time | Waits for a specified amount of time | g.waitfor\_time(1) | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| waitfor\_frames | Waits for a number of total good frames to reach parameter value | g.waitfor\_frames(1000) | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| waitfor\_uamps | Waits for a specific total charge | g.waitfor\_uamps(9.9) | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| waitfor\_runstate | Waits for a particular instrument run state | g.waitfor\_runstate("paused") | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ +| waitfor\_move | Waits for all motion or specific motion to complete | g.waitfor\_move("NEW\_BLOCK") | ++---------------------+-----------------------------------------------------------------------------------------+------------------------------------+ + + +Toggling options +---------------- +Various options can be toggled with the ``toggle`` command. + +For example, toggling the verbosity of all calls to a command using ``toggle.cset_verbose(True)``. This can be convenient, as there will be no need to explicitly set ``verbose=True`` for each ``cset`` call. + +There are also advanced options such as ``toggle.exceptions_raised(True)``, which will allow exceptions to propagate instead of genie handling them, in case you want to handle exceptions yourself. WARNING: If you have this toggled to True and there is an exception within genie_python it will stop your script from running unless you catch the exception yourself. + +.. _`genie\_python reference manual`: http://shadow.nd.rl.ac.uk/genie\_python/sphinx/genie\_python.html diff --git a/doc/scripting/training_course/AutoCompleteWindowBasic.png b/doc/scripting/training_course/AutoCompleteWindowBasic.png new file mode 100644 index 0000000..c50a123 Binary files /dev/null and b/doc/scripting/training_course/AutoCompleteWindowBasic.png differ diff --git a/doc/scripting/training_course/StandardStartupOutputOnDemo.png b/doc/scripting/training_course/StandardStartupOutputOnDemo.png new file mode 100644 index 0000000..d2f3163 Binary files /dev/null and b/doc/scripting/training_course/StandardStartupOutputOnDemo.png differ diff --git a/doc/scripting/training_course/genie_python-and-IBEX-(Closing-remarks).rst b/doc/scripting/training_course/genie_python-and-IBEX-(Closing-remarks).rst new file mode 100644 index 0000000..0fc3f10 --- /dev/null +++ b/doc/scripting/training_course/genie_python-and-IBEX-(Closing-remarks).rst @@ -0,0 +1,4 @@ +Closing remarks +############### + +Thank you for taking this course, we hope you've enjoyed it. Please forward any feedback to the IBEX team. Happy coding! diff --git a/doc/scripting/training_course/genie_python-and-IBEX-(Common-commands).rst b/doc/scripting/training_course/genie_python-and-IBEX-(Common-commands).rst new file mode 100644 index 0000000..00b87a8 --- /dev/null +++ b/doc/scripting/training_course/genie_python-and-IBEX-(Common-commands).rst @@ -0,0 +1,230 @@ +Common commands +############### + +Calling ``genie_python`` functions +=================================== + +From an IBEX scripting terminal, ``genie_python`` commands can be accessed via the ``g`` namespace. For example: ``g.get_version()`` + +You should have noticed immediately after you typed ``g.`` that an auto-complete window appeared: + +.. image:: AutoCompleteWindowBasic.png + +The window lists the available commands, and the arguments they take, in brackets. A description of the highlighted functions and its arguments is also given. The list will be refined as you type more characters. + + +Passing arguments to commands +============================= + +Arguments are passed to functions using standard Python syntax. You should already be somewhat familiar with this but here is a quick recap: + +- Arguments are passed to functions as a comma-separated list within brackets. For example ``g.add_spectrum(1, 2)`` +- Arguments may be named or not. For example ``g.add_spectrum(spectrum=1, period=2)`` +- Named and un-named arguments can be mixed but the named arguments must appear last. For example ``g.add_spectrum(1, period=2)`` +- Un-named arguments will be interpreted in the order of the function definition. Named arguments can be in any order. So ``g.add_spectrum(period=2, spectrum=1)`` would be valid but ``g.add_spectrum(2, spectrum=1)`` would not. +- Some arguments may be defaulted in which case they do not need to be included in the argument list. For example ``g.add_spectrum(1)`` is equivalent to ``g.add_spectrum(1, 1)``. You can find out which parameters are optional and their default values in :external+genie_python:py:mod:`genie`. + +As another example, the following three calls are all equivalent: + +.. code-block:: python + + g.end() + g.end(False) + g.end(verbose=False) + +Acquisition control +=================== + +Switch run states +----------------- + +``genie_python`` provides commands to switch between various run states: + +- ``begin``: Begins a new run +- ``pause``: Pauses the current run +- ``resume``: Resumes the current run +- ``end``: Ends the current run +- ``abort``: Aborts the current run + +You can get the current state with: + +- ``get_runstate``: Gets the states of the current run + +**WARNING**: Be careful not to assume the resultant state when using these commands. For example, you may run ``g.begin()`` and then expect the instrument to be running. That may be true, but it could also be waiting, vetoing, or still setup. It's a good idea to put checks into your scripts that you've reached the expected state. This can be done with ``waitfor_runstate``: + +.. code-block:: python + + g.begin() + # Waits for a max of 60 seconds + g.waitfor_runstate("RUNNING", 60) + + +Waiting +------- + +If you want to wait for a specific event before executing an action, you can use one of the ``waitfor_...`` commands: + +- ``waitfor_block``: Wait for a block value to be in a certain range +- ``waitfor_frames``: Wait until the number of good frames reaches a certain value +- ``waitfor_uamps``: Wait for the total received current to reach 10 uamps +- ``waitfor_time``: Waits for a specified time. The best way to use this function is with named arguments (e.g. ``g.waitfor_time(seconds=10)``) to make it clear what time units the interval is in. +- ``waitfor_move``: Waits for all motors, or a specific motor, to finish moving +- ``waitfor_runstate``: Wait for the instrument to reach a given state + +This is only a subset of the available functions. For a full list see :external+genie_python:py:mod:`genie`. + +Update and store +------------------ + +You can update and store DAE results using: + +- ``update``: Load the data from the DAE into memory +- ``store``: Write the updated DAE information to disk +- ``updatestore``: Load the data from the DAE into memory and store it to disk + +Worked example +-------------- + +The following script will begin and run, then stop it once it reaches a running state: + +.. code-block:: python + + # Only start if we're in the correct state + if g.get_runstate()=="SETUP": + g.begin() + + # Check that the run has started successfully + if g.get_runstate()=="RUNNING": + + # A function that does the sequence of operations associated with the run + do_experimental_stuff() + + else: + print ("Could not reach a running state") + + + +Blocks +======== + +- ``get_blocks``: Gets a list of the currently available blocks +- ``cshow``: Shows the properties of a named block/all blocks + + - If given a name (e.g. ``MY_BLOCK``) it will return a string containing properties of the block + + - Example: ``MY_BLOCK = 10 (runcontrol = NO, lowlimit = 0.0, highlimit = 0.0)`` + + - If called without arguments, it will show the same information for all blocks, with each block on a new line + +- ``cget``: Gets properties of a named block as a dictionary of values + + - Example: ``MY_BLOCK = 10 (runcontrol = NO, lowlimit = 0.0, highlimit = 0.0)`` + - Unlike ``cshow``, a block name must be specified + - Properties can be accessed as standard Python: + +.. code-block:: python + + block_info = g.cget("MY_BLOCK") + name = block_info["name"] + value = block_info["value"] + print ("The value of block {0} is {1}".format(name, value)) + +- ``cset``: Sets the value for a particular block + + - Assumes that either a setpoint exists for the underlying value or the block itself points at a setpoint + - Can be called with block names as named arguments. This is useful for setting multiple blocks + + - Example: ``g.cset(MY_BLOCK=1, MY_OTHER_BLOCK=2)`` + + - The block can also be passed in by name. This is useful when setting advanced block properties + + - Example: ``g.cset("MY_BLOCK", lowlimit=1, highlimit=10, runcontrol=True)`` + + +Worked example +---------------- + +The following script scans a block between its upper and lower limit: + +.. code-block:: python + + # Set some parameters + max_steps = 100 + high_limit = 10 + low_limit = 1 + block = "MY_BLOCK" + abs_step_size = 1 + + # Set the initial conditions + g.cset(block, lowlimit = low_limit, highlimit = high_limit) + step_size = abs_step_size + + # Run the scan + for i in range(max_steps): + block_properties = g.cget(block) + current_value = block_properties['value'] + + # Block at or below low limit: Set step positive + if current_value <= block_properties['lowlimit']: + step_size = abs_step_size + + # Block at or below high limit: Set step negative + if current_value >= block_properties['highlimit']: + step_size = -abs_step_size + + g.cset(block, current_value + step_size) + g.waitfor_time(seconds=0.1) + +Experiment setup +---------------- + +You can change various elements of the experiment setup using ``genie_python``. For example: + +- ``change_tcb``: Change the time channel boundaries +- ``change_tables``: Change the wiring, spectra and detector table filename used +- ``change_monitor``: Change the monitor to a specified spectrum and range + +If used on their own, these methods will apply their changes immediately. Sometime a set of changes are only consistent/make sense when considered together. If you want to apply several changes at once you can use the following commands: + +- ``change_start``: Marks the start of a change +- ``change_finish``: Marks that the current set of changes is complete. All changes recorded since ``g.change_start()`` will be applied + +Using these commands will stop a run beginning while changes are still being made. + +Experiment details +------------------ + +You can change various experiment details with the ``change_...`` commands: + +- ``change_user``: Change the current user +- ``change_title``: Change the current title +- ``change_rb``: Change the current RB number + +There is a generic `change` command that allows you to change multiple properties simultaneously. However, this is recommended for advanced users only. + +You can get the current setup using the equivalent ``get_...`` commands: + +- ``get_user``: Get the current user +- ``get_title``: Get the current title +- ``get_rb``: Get the current RB number + +.. _gp_and_ibex_ex2: + +**Exercise 2** +============== + +- This exercise requires that: + + - You have permission to begin and end runs on the instrument you're using. + - The instrument you're using has been configured so it can successfully enter a running state + - You have a settable block called "MY_BLOCK" + +- Change the title of the run to "Exercise 2" +- Start a run and wait for 1 uamps before pausing +- Set the value of "MY_BLOCK" to 5, with a high limit of 10, a low limit of 1 and put it under run control +- Resume the run +- Set the value of "MY_BLOCK" to 20 and confirm (using ``genie_python``) that the instrument has entered a waiting state +- Decrease the value of "MY_BLOCK" down in steps of 1 until it reaches 10. Wait for 1 second between steps. Notice how the run state changes back to running when the block value drops below 10. +- End the run + +:ref:`Solution` diff --git a/doc/scripting/training_course/genie_python-and-IBEX-(Converting-from-Open-GENIE).rst b/doc/scripting/training_course/genie_python-and-IBEX-(Converting-from-Open-GENIE).rst new file mode 100644 index 0000000..d9a5f19 --- /dev/null +++ b/doc/scripting/training_course/genie_python-and-IBEX-(Converting-from-Open-GENIE).rst @@ -0,0 +1,304 @@ +Converting from OpenGENIE +######################### + +Open GENIE: Compare and contrast +================================ + +Procedures vs. functions +------------------------ + +In ``Open GENIE``, procedures are defined by the keyword ``PROCEDURE`` and end with the keyword ``ENDPROCEDURE``. In Python we instead define functions using the ``def`` keyword so that:: + + PROCEDURE my_function + ... + ENDPROCEDURE + +becomes: + +.. code-block:: python + + def my_function(): + ... + +Note that, using Python syntax, we don't need a statement to show where the function ends; the indentation takes care of that for us. + +We pass arguments into ``Open GENIE`` procedures like this:: + + PROCEDURE my_function + PARAMETERS x = Integer y = Real z = String + ... + ENDPROCEDURE + +Usually an expected type is given for a parameter, this is not necessary but can trap common errors. We can do a similar thing in ``genie_python``, but we don't define the type of the parameters. Python will only complain at run time if you call an unsupported operation on the input arguments. In ``genie_python``, the code above becomes: + +.. code-block:: python + + def my_function(x, y, z): + ... + +Loops +----- + +In ``Open GENIE`` a loop is defined using:: + + LOOP I FROM start TO end + ... + ENDLOOP + +The code above translates into Python as: + +.. code-block:: python + + for i in range(start, end+1): + ... + +No ``ENDLOOP`` is needed because the indentation makes it implicit. + +Conditionals +------------ + +In ``Open GENIE`` conditionals take the form:: + + IF [CONDITION] + ... + ELSE + ... + ENDIF + +In Python this is written as: + +.. code-block:: python + + if [CONDITION]: + ... + else: + ... + +No ``ENDIF`` is needed because the indentation makes it implicit. + + +Commands +-------- + +The majority of ``Open GENIE`` instrument control commands have a very close equivalent in ``genie_python``. + +For example, the ``Open GENIE`` command:: + + BEGIN + +in ``genie_python`` becomes: + +.. code-block:: python + + g.begin() + +Similarly, the ``Open GENIE`` command:: + + CHANGE TITLE="New title" + +in ``genie_python`` becomes: + +.. code-block:: python + + g.change_title("New title") + +Similarly, most arguments will be very similar between ``Open GENIE`` and ``genie_python``. For example, the following ``Open GENIE`` command:: + + CSET/CONTROL TEMP1=5 LOWLIMIT=1 HIGHLIMIT=10 + +becomes the following in ``genie_python``: + +.. code-block:: python + + g.cset(TEMP1=5, runcontrol=True, lowlimit=1, highlimit=10) + +**NOTE** Python is case sensitive and the arguments, apart from the block name, are in lower case + +Worked example +-------------- + +Take the following ``Open GENIE`` procedure:: + + PROCEDURE my_function + + GLOBAL temp high low pow count + + temp = 20 + low = 1 + high = 50 + + CSET/CONTROL TEMP1=temp LOWLIMIT=low HIGHLIMIT=high + CSET/CONTROL TEMP2=temp LOWLIMIT=low HIGHLIMIT=high + + CHANGE TITLE= "Running at temperature "+As_string(temp) + BEGIN + WAITFOR UAMPS=0.2 + ABORT + PRINTN "waiting 10 minutes" + WAITFOR SECONDS=60*10 + BEGIN + WAITFOR SECONDS=10 + PRINTN "Waiting for "+As_string(count)+"uAh" + WAITFOR UAMPS=count + END + + ENDPROCEDURE + +Let's convert it to ``genie_python``. First of all we turn the ``PROCEDURE`` into a Python function: + +.. code-block:: python + + def my_function(): + +We haven't given any arguments, because the procedure has no parameters. + +The variable definitions remain the same, except we don't need the ``GLOBAL`` line to define our variables. However this function might be reused with different temperatures and limits, in which case we could change: + +.. code-block:: python + + def my_function(): + temp = 20 + low = 1 + high = 50 + +to: + +.. code-block:: python + + def my_function(temp, low, high): + +We can always create a function to call specific parameters if needed: + +.. code-block:: python + + def my_specific_function(): + my_function(temp=20, low=1, high=50) + +Further, we notice that ``WAITFOR`` later in the function waits for 50 microamps. Let's assume we almost always want to wait for 50 microamps but we'd like the possibility to override it sometimes. In that case, we can make it a 4th parameter with a default value, like so: + +.. code-block:: python + + def my_function(temp, low, high, count=50): + +Let's start looking at the content of the PROCEDURE: + + CSET/CONTROL TEMP1=temp LOWLIMIT=low HIGHLIMIT=high + +In ``genie_python``, this becomes: + +.. code-block:: python + + g.cset(TEMP1=temp, lowlimit=low, highlight=high, runcontrol=True) + +The same goes for ``TEMP2``, but that gives us two commands that do exactly the same thing. That's not generally a good idea because it's prone to typos and changes to one line might not be applied to the other. It would be much better to do the following: + +.. code-block:: python + + for block in ["TEMP1", "TEMP2"]: + g.cset(block, temp, lowlimit=low, highlimit=high, runcontrol=True) + +Notably we've had to use the alternate ``cset`` argument syntax in this case. + +The next block of commands is:: + + CHANGE TITLE= "Running at temperature "+As_string(temp) + BEGIN + WAITFOR UAMPS=0.2 + ABORT + PRINTN "waiting 10 minutes" + WAITFOR SECONDS=60*10 + BEGIN + WAITFOR SECONDS=10 + PRINTN "Waiting for "+As_string(count)+"uAh" + WAITFOR UAMPS=count + END + +These translate very directly into ``genie_python``: + +.. code-block:: python + + g.change_title("Running at temperature {0}".format(temp)) + g.begin() + g.waitfor_uamps(0.2) + g.abort() + minutes_to_wait = 10 + print "Waiting {0} minutes".format(minutes_to_wait) + g.waitfor_time(minutes=minutes_to_wait) + g.begin() + g.waitfor_time(seconds=10) + print "Waiting for {0}uAh".format(count) + g.waitfor_uamps(count) + g.end() + +We've changed a couple of things: + +- Rather than use the value ``10`` for the number of minutes to wait, we've set it as a variable. That means if we change the value, we only need to change it in one place. +- We've used the ``minutes`` argument in ``waitfor_time`` rather than having to apply the conversion factor between minutes and seconds ourselves. +- We've used the syntax ``"...".format(arg1, arg2)`` to build our output strings. There are lots of ways to build strings in Python. Alternatively you can just use ``"..." + str(arg1) + "..." + str(arg2) + "..."`` but we like this way because it makes it easier to read and you don't have to remember to use ``str(...)`` to convert the types + +The final ``ENDPROCEDURE`` command doesn't need an equivalent in ``genie_python``. Our final script is therefore: + +.. code-block:: python + + def my_function(temp, low, high, count=50): + for block in ["TEMP1", "TEMP2"]: + g.cset(block, temp, lowlimit=low, highlimit=high, runcontrol=True) + + g.change_title("Running at temperature {0}".format(temp)) + g.begin() + g.waitfor_uamps(0.2) + g.abort() + + minutes_to_wait = 10 + print "Waiting {0} minutes".format(minutes_to_wait) + g.waitfor_time(minutes=minutes_to_wait) + + g.begin() + g.waitfor_time(seconds=10) + print "Waiting for {0}uAh".format(count) + g.waitfor_uamps(count) + g.end() + + def my_specific_function(): + my_function(temp=20, low=1, high=50) + +.. _gp_and_ibex_ex5: + +Exercise 5 +========== + +- Translate the following ``Open GENIE`` script into ``genie_python``:: + + PROCEDURE Scan + LOCAL i setpoint max min start step_size title nframes nimages multip + + max = 200.0; min = 100.0 + nframes = 10; nimages = 10; step_size = 20.0; setpoint = 0.0; start = -100.0 + setpoint = start + + LOOP i FROM 1 TO nimages + setpoint = setpoint + step_size + multip = As_Integer(setpoint/360) + setpoint = setpoint - 360*multip + PRINTN "New angle is: " + as_string(setpoint) + + IF (setpoint>=min) OR (setpoint<=max) + + tempTitle="Image "+as_string(i)+", "+as_string(setpoint)+" degrees" + CHANGE TITLE=tempTitle + cset POSITION=setpoint + waitformove + PRINTN "Move complete. Counting for "+As_String(nframes)+" frames" + BEGIN + WAITFOR frames=nframes + END + ELSE + PRINTIN "Value "+As_string(setpoint)+ " not in interval" + ENDIF + ENDLOOP + ENDPROCEDURE + +- State any simplifications you've made + + +:ref:`Solution` diff --git a/doc/scripting/training_course/genie_python-and-IBEX-(Exercise-solutions).rst b/doc/scripting/training_course/genie_python-and-IBEX-(Exercise-solutions).rst new file mode 100644 index 0000000..3e0c86d --- /dev/null +++ b/doc/scripting/training_course/genie_python-and-IBEX-(Exercise-solutions).rst @@ -0,0 +1,208 @@ +Exercise Solutions +################## + +.. _gp_and_ibex_ex1_solution: + +Exercise 1 +========== + +From :ref:`gp_and_ibex_ex1`. + +- Opening a scripting window should be straightforward if IBEX is installed correctly. Once you've opened the scripting perspective, check for the following + + - Ideally the instrument will appear as ``SETUP`` + - The output when the scripting window opens should look a bit like this: + +.. image:: StandardStartupOutputOnDemo.png + +- To print the message, enter something like ``print "Hello, World!`` and press return + +- The square of the integers between 1 and 10 can be output with the code below. A **blank line** will indicate to the scripting window that you've finished writing the loop and it can go ahead and be executed.: + +.. code-block:: python + + for i in range(1,11): + print i*i + +.. _gp_and_ibex_ex2_solution: + +Exercise 2 +========== + +From :ref:`gp_and_ibex_ex2` + +- Use ``g.change_title("Exercise 2")`` to change the title +- The following code will start the run, wait, and then pause: + +.. code-block:: python + + g.begin() + g.waitfor_uamps(1) + g.pause() + +- This code sets the value, run control, and limits on "MY_BLOCK". Your code may look slightly different depending how you've chosen to pass in the arguments: + +.. code-block:: python + + g.cset("MY_BLOCK", 5, lowlimit=1, highlimit=10, runcontrol=True) + +- The following resumes the run: + +.. code-block:: python + + g.resume() + +- This code will set the block value and check the subsequent state: + +.. code-block:: python + + # Can use either way of specifying cset for a single block + g.cset(MY_BLOCK=20) + + # Can verify in any sensible way, so long as we're getting g.get_runstate() + if g.get_runstate()=="WAITING": + print "The instrument is waiting" + else: + print "The instrument is not waiting" + +- The following code will scan the block from its original value down to 4. It assumes the initial value is greater than 4: + +.. code-block:: python + + for i in range(int(g.cget("MY_BLOCK")['value']), 4, -1): + g.cset(MY_BLOCK=i) + g.waitfor_time(seconds=1) + +- This function will end the run: + +.. code-block:: python + + g.end() + +.. _gp_and_ibex_ex3_solution: + +Exercise 3 +========== + +From :ref:`gp_and_ibex_ex3`. + +- **(a)** After creating the files, you should have one new file in ``C:\scripts`` and another in ``C:\Instrument\Settings\config\[Instrument name]\Python\inst`` + +- **(b)** The function in ``set_up_instrument.py`` should look something like this: + + def set_up_instrument(): + g.change_title("My experiment") + g.change_user("Adrian") + +- **(b)** The function in ``run_my_experiment.py`` should look something like this: + +.. code-block:: python + + def get_uamps_run(): + g.begin() + # Assume this doesn't change + period = g.get_period() + for i in range(10): + print "Total current after {0}s: {1}.format(i+1, g.get_uamps(period)) + g.waitfor_time(seconds=1) + g.end() + +- **(c)** This will load the user script: ``g.load_script("run_my_experiment.py")`` + +- **(d)** This will run the instrument script: ``inst.set_up_instrument()`` + +- **(e)** This will run the function from the user script ``get_uamps_run()`` + +.. _gp_and_ibex_ex4_solution: + +Exercise 4 +========== + +From :ref:`gp_and_ibex_ex4`. + +- You should have created a Python file in ``C:\Instrument\Settings\config\[Machine name]\Python\inst`` that contains something like the following: + +.. code-block:: python + + from genie_python import genie as g, BLOCK_NAMES as b + + def ramp(block, target): + try: + initial = g.cget(block)['value'] + except: + print "Problem getting value for block {0}. Make sure it exists".format(block) + else: + g.change_title("Ramping {0} from {1} to {2}".format(block, initial, target)) + g.begin() + + current = initial + small = 0.0001 + while abs(current-target) > small: + current = min(target, current + 1) if initial < target else max(target, current -1) + g.cset(block, current) + finally: + g.end() + +- Once you add the line to output the current title, the top of your file should look like this: + +.. code-block:: python + + print g.get_title() + def ramp(block, target): + ... + +- This user-defined function will ramp the two blocks using the instrument function: + +.. code-block:: python + + def ramp_two_blocks(): + for block, target in [("MY_BLOCK", 10), ("MY_OTHER_BLOCK", -10)]: + inst.ramp(block, target) + +- To load the user script, assuming the file is called "ramp_blocks.py", run the following from the scripting perspective: + +.. code-block:: python + + g.load_script("C:\scripts\ramp_blocks.py") + ramp_two_blocks() + +- You should have seen the current title printed during the initialisation of the scripting window + +.. _gp_and_ibex_ex5_solution: + +Exercise 5 +========== + +From :ref:`gp_and_ibex_ex5`. + +- In ``genie_python``, the ``Open GENIE`` procedure could be written as: + +.. code-block:: python + + def scan(start=-100, min=100, max=200, step_size=20, nframes=10, nimages=10): + for i in range(1, nimages+1): + setpoint = (start + i*step_size) % 360 + print "New angle is: {0}".format(setpoint) + + if min <= setpoint <= max: + g.change_title("Image {0}: {1} degrees".format(i, setpoint)) + g.cset(POSITION=setpoint) + g.waitfor_move() + + print "Move complete. Counting for {0} frames".format(nframes) + g.begin() + g.waitfor(frames=nframes) + g.end() + else: + print "Not in interval {1}<={0}<={2}".format(setpoint, min, max) + +- We've made the following simplifications: + + - We've put the key variables as defaulted input arguments. This allows for maximal flexibility. In reality, which variables we put as arguments and which we default will depend on context. It's not recommended to put everything as an argument and always provide defaults + - We've taken advantage of several pieces of Python syntax to simplify the logic + + - ``"...".format(*args)`` for constructing strings + - Defining a range as a single condition ``a <= b <= c`` + - Taking the modulo of a number using ``%`` to avoid extra calculations + - Removing the unused line ``setpoint = 0.0`` + - Several commands are unnecessary in Python, namely ``LOCAL``, ``ENDLOOP``, ``ENDIF``, ``ENDPROCEDURE`` \ No newline at end of file diff --git a/doc/scripting/training_course/genie_python-and-IBEX-(Getting-started).rst b/doc/scripting/training_course/genie_python-and-IBEX-(Getting-started).rst new file mode 100644 index 0000000..9b2a27b --- /dev/null +++ b/doc/scripting/training_course/genie_python-and-IBEX-(Getting-started).rst @@ -0,0 +1,35 @@ +Getting Started +############### + +Starting a scripting session +============================ + +From IBEX +--------- + +The best way to run ``genie_python`` commands is from the scripting perspective of the IBEX client. + +To open a scripting window: + +1. Start the IBEX client +2. Open the scripting perspective + +.. image:: ../OpenTheScriptingPerspective.png + +3. From here, you can start entering Python code. It will be executed line by line as you enter it. + +Outside IBEX +------------ + +You can also open a scripting terminal by running ``C:\Instrument\Apps\Python\genie_python.bat`` but this is recommended for advanced users only. + +.. _gp_and_ibex_ex1: + +**Exercise 1** +============== + +- Open a scripting window in IBEX +- Output "Hello, world!" to the console +- Output the square of all the integers between 1 and 10 + +:ref:`Solution` diff --git a/doc/scripting/training_course/genie_python-and-IBEX-(Introduction).rst b/doc/scripting/training_course/genie_python-and-IBEX-(Introduction).rst new file mode 100644 index 0000000..11e0041 --- /dev/null +++ b/doc/scripting/training_course/genie_python-and-IBEX-(Introduction).rst @@ -0,0 +1,31 @@ +Introduction +############ + +Introduction +============ + +Welcome to this introductory course on ``genie_python``, a Python module that enables instrument control using Genie commands with Python. Once you have completed this course, you will be able to do the following from the scripting perspective in IBEX: + +- Start and stop runs +- Get and set block information +- Update experiment details +- Call specialised instrument and user scripts +- Convert ``Open GENIE`` scripts to ``genie_python`` + +At each stage, the course aims to assist learning with exercises and worked examples. We will assume a basic working knowledge of Python. If you've never programmed in Python before, we recommend the :external+mantid:ref:`introduction_to_python` from the Mantid project. + +The slides accompanying this course can be found :download:`here` + +``genie_python`` does not cover data analysis. If you want to do analysis that can't be achieved with basic Python, we recommend the :external+mantid:ref:`Python in Mantid training course`. + +Contents +======== + +The course is broadly split up into the following topics + +- :doc:`genie_python-and-IBEX-(Getting-started)` +- :doc:`genie_python-and-IBEX-(Common-commands)` +- :doc:`genie_python-and-IBEX-(Scripting)` +- :doc:`genie_python-and-IBEX-(Converting-from-Open-GENIE)` +- :doc:`genie_python-and-IBEX-(Closing-remarks)` +- :doc:`genie_python-and-IBEX-(Exercise-solutions)` diff --git a/doc/scripting/training_course/genie_python-and-IBEX-(Scripting).rst b/doc/scripting/training_course/genie_python-and-IBEX-(Scripting).rst new file mode 100644 index 0000000..977a492 --- /dev/null +++ b/doc/scripting/training_course/genie_python-and-IBEX-(Scripting).rst @@ -0,0 +1,209 @@ +Scripting +######### + +Introduction +============ + +So far we have run ``genie_python`` commands by entering them via a terminal. However, there may be cases where we want to reuse common sets of commands multiple times. These cases are where creating a script can be very useful. + +Creating scripts +================ + +Python scripts have the extension ``.py``. You can create them from any number of editors. A good editor will do syntax highlighting, and will make it easy to work with Python's indented blocks without accidentally mixing spaces and tabs. Notepad++ is a good choice. + +We generally classify scripts as: + +1. **Instrument scripts**. These are either aimed at instrument scientists, or put the instrument in a particular state that multiple users may wish to access. +2. **User scripts**. These are scripts that specific users need for particular experiments. They may be reused to an extent but they don't generally need to be accessed quite so readily. + +**NOTE**: IBEX puts all configurations and **Instrument scripts** under version control. That means if you change or delete them and want to restore a previous version, you can. The same isn't true for user scripts. + +- Instrument scripts are located in: ``C:\Instrument\Settings\config\NDX[Instrument name]\Python\inst`` +- User scripts are located in: ``C:\scripts`` + +.. _gp_and_ibex_ex3: + +Exercise 3a +----------- + +Create two empty scripts: + +- An **instrument** script called ``set_up_instrument.py`` +- A **user** script called ``run_my_experiment.py`` + +:doc:`Solution` + +Writing scripts +=============== + +When writing scripts, you can use any Python and ``genie_python`` functionality that you've already learnt. **In instrument scripts, you must have this as your first line:** + +.. code-block:: python + + from genie_python import genie as g, BLOCK_NAMES as b + +In general, we recommend all executable code within a script should be contained within functions and classes. For example: + +.. code-block:: python + + def my_function(arg1, arg2): + print "The first argument is {0}, the second argument is {1}".format(arg1, arg2) + +This gives much greater control over when and how custom code is executed. + +Exercise 3b +----------- + +- Update your instrument script, ``set_up_instrument.py``, so that it contains a single function + + - The function should be called "set_up_instrument" + - It should set the title to "My experiment" + - It should set the username to your name + +- Update your user script, ``run_my_experiment.py`` which contains a function that does the following + + - Begins the run + - Prints the current uamps for the current period over 10 seconds at 1 second intervals + - Ends the run + +:ref:`Solution` + +Loading scripts +=============== + +Once you've created your scripts, you need to make sure they're available to use. This works differently for instrument scripts and user scripts. + +- **Instrument scripts** are loaded automatically when you open the scripting perspective +- **User scripts** can be loaded by using the ``load_script`` method in genie_python. For example, ``g.load_script('C:\scripts\run_my_experiment.py')``. ``g.load_script`` looks automatically in ``C:\scripts``. A full path can be given for other locations + + +**IMPORTANT**: When a script is loaded, Python runs all the commands contained within. We strongly recommend keeping all executable code within functions, so that it runs when you call it rather than executing immediately. + +Exercise 3c +----------- + +Load your user script ``run_my_experiment.py`` + +:ref:`Solution` + +Running scripts +=============== + +Instrument scripts +------------------ + +Methods defined in instrument scripts are available via the ``inst`` namespace. For example, if we define a method called ``my_method`` in an instrument script which takes 1 argument, a block name, then I can make it run in the scripting perspective by entering: + +.. code-block:: python + + inst.my_method("MY_BLOCK") + +As with ``genie_python`` commands, the IBEX scripting perspective will provide auto-completion for instrument methods so you can see what is available + +Exercise 3d +----------- + +Run the instrument method you wrote in exercise 3b + +:ref:`Solution` + +User scripts +------------ + +Functions loaded from user scripts using the ``g.load_script(...)`` command will be available to call like any other user-defined function. For example, if I defined a function ``my_function``: + +.. code-block:: python + + g.load_script("my_script_file.py") + my_function() + +Exercise 3e +----------- + +Run the user script method you wrote in exercise 3b + +:ref:`Solution` + +Modifying scripts +================= + +Every new scripting perspective will be a clean slate; any previously loaded scripts will be forgotten. A new scripting perspective is opened each time IBEX is started, but your scripting session will be preserved if you switch between views without closing the client. + +Sometimes you might want to change a script and update it without having to change scripting terminal. + +- Instrument scripts: Run the command ``reload(inst)`` +- User scripts: Run ``g.load_script("C:\scripts\file_to_reload.py")`` with the appropriate file name + +Exercise 3f +----------- + +- Modify your instrument script to output the current at 0.1 second intervals +- Reload the script +- Run it again and confirm the behaviour has changed + +:ref:`Solution` + +Using functions from other files +================================ + +You may want to call a function from one file in another file. + +Calling an instrument function from a different instrument script +----------------------------------------------------------------- + +It is recommended that you ``import`` it using standard Python rather than trying to call it with the ``inst.`` because you don't know the order in which the scripts are loaded. For example, if I have one instrument script, ``counts.py``: + +.. code-block:: python + + def vanadium(title, duration): + g.change_title(title) + g.begin() + g.waitfor_time(seconds=duration) + g.end() + +and another called ``calibrate.py`` that uses the ``vanadium`` function then I would write: + +.. code-block:: python + + from counts import vanadium + def calibration(): + for title, duration in [("10 second run", 10), ("1 minute run", 60), ("1 hour run", 3600)]: + vanadium(title, duration) + +Calling an instrument function from a user script +------------------------------------------------- + +Here you can just use ``inst.`` prefix, for example ``inst.my_function(arg1, arg2)`` + +Calling a user function from an instrument script +------------------------------------------------- + +This is feasible, but generally not recommended. The user script won't be kept in version control like the instrument script and could be moved or changed unexpectedly. + +Calling a user function from a different user script +---------------------------------------------------- + +The same as calling a function in one instrument script from another. + +.. _gp_and_ibex_ex4: + +Exercise 4 +========== + +- Create a new instrument script containing a function + + - The function sets the title to "Ramping [block name] from [initial value] to [final value]" + - The block name, initial and final values should all be provided as input arguments + - The method begins a run and then changes the value of the block incrementally in steps of size 1 + - Once the target is reached, the method ends the run + +- Put a line at the top of your instrument script **outside the function definition** that prints the current title + +- Create a new user script containing a function + + - The function runs the new instrument script on two different blocks + +- Load and run your new user-script function +- When was the print statement at the top of your instrument script executed? + +:ref:`Solution` diff --git a/doc/scripting/training_course/genie_python_and_ibex.pptx b/doc/scripting/training_course/genie_python_and_ibex.pptx new file mode 100644 index 0000000..5aad817 Binary files /dev/null and b/doc/scripting/training_course/genie_python_and_ibex.pptx differ diff --git a/doc/spelling_wordlist.txt b/doc/spelling_wordlist.txt new file mode 100644 index 0000000..1a6c3db --- /dev/null +++ b/doc/spelling_wordlist.txt @@ -0,0 +1,89 @@ +archiver +asyn +autocomplete +autosave +autosaved +backend +beamline +beamlines +blockserver +boolean +casted +CCR +cget +comms +config +cset +ctrl +customisable +Danfysik +datafile +dataset +dataweb +deadband +delevitate +enums +Eurotherm +exe +executables +filesystem +func +Futurize +Galil +globals +Grafana +gui +histogrammed +inits +INSTNAME +ioc +Julabo +LabVIEW +Lakeshore +llb +mA +Mantid +matplotlib +mevents +microamps +namespace +nxs +ok +plottable +pre +pv +py +pylint +pypi +pyplot +pyright +readback +readbacks +reflectometer +reflectometers +reflectometry +requesters +resends +runcontrol +runstate +runtime +setpoint +setpoints +subdomain +supermirror +synoptic +synoptics +th +ToF +totalcounts +txt +uA +uamps +ueip +un +unicodeescape +uninstallation +unprefixed +untick +ve +waitfor diff --git a/doc/temporary_run_control_setting.PNG b/doc/temporary_run_control_setting.PNG new file mode 100644 index 0000000..1b6c684 Binary files /dev/null and b/doc/temporary_run_control_setting.PNG differ diff --git a/doc/web_dashboard/Grafana-Dashboard.md b/doc/web_dashboard/Grafana-Dashboard.md new file mode 100644 index 0000000..444603a --- /dev/null +++ b/doc/web_dashboard/Grafana-Dashboard.md @@ -0,0 +1,15 @@ +# Grafana Dashboard + +ISIS staff are able to access an enhanced web dashboard plotting mechanism via the site https://svr2.nd.rl.ac.uk/grafana/ - login must be by federal id (without CLRC prefix). + +## Plotting Multiple Traces + +Once logged in, if you click on the "compass" icon on the left (called "explore") at the top of the page you will then see a "metrics browser" where you can choose a logged item from an instrument. You can either type something into the box to search box (case sensitive) or click on the "metrics browser" menu and choose an item. Logged Blocks on instruments will start with the instrument name and end with `_value` e.g. `IMAT_block_C1D1_FREQ_value`. After that, you can then add further queries to the same graph to get multiple traces (you may need to press `Run Query` after adding a new trace). These additions are then remembered in the "query history", when you "clear all" it starts a new item in the query history. This query history is per browser, so if you log in again with the same browser you should be able to go straight to a previous query you made (query history is saved for a few weeks). If you add multiple traces to a graph, you can click on individual trace names displayed below the graph to see just that line, and then click again to evert back. At one time i though "control click" gave additional control, but maybe not anymore. + +## Creating and Saving Dashboards + +**Note:** you are welcome to experiment with this feature, but **please do not invest too much time** at the moment in creating dashboards as the Grafana system is still in evaluation and may not be the permanent eventual solution to web dashboard history. + +It is possible for you to create, save and share your own custom panels of plots - these are called dashboards. To see an example click on the 4 squares icon that gives you the dashboard menu, choose Manage, then click on the IBEX folder and then on "example" – this dashboard displays two panels, a graph and a table. It is possible to create lots of separate dashboards with panels and tables and save them to the server in a folder. You just click on the "+" icon to create a dashboard, which can later be made visible to all or just selected people. It is best to create dashboards in a folder, then permissions can be applied to the folder rather than each individual dashboard in it. So keep dashboards for "users + staff" and "staff only" in separate folders. You will need to contact ISIS Experiment Controls group to change folder permissions if you wish to remove default user access. + +See https://grafana.com/docs/grafana/latest/getting-started/getting-started/ for more details diff --git a/logo.svg b/logo.svg new file mode 100644 index 0000000..a218177 --- /dev/null +++ b/logo.svg @@ -0,0 +1,9 @@ + + ibex-logo + + + + diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..99f4ca4 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,46 @@ +[build-system] +requires = ["setuptools", "setuptools_scm>=8"] +build-backend = "setuptools.build_meta" + +[project] +name = "ibex_user_manual" +dynamic = ["version"] +description = "IBEX User's manual" +readme = "README.md" +requires-python = ">=3.10" + +authors = [ + {name = "ISIS Experiment Controls", email = "ISISExperimentControls@stfc.ac.uk" } +] +maintainers = [ + {name = "ISIS Experiment Controls", email = "ISISExperimentControls@stfc.ac.uk" } +] + +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Developers", + "Programming Language :: Python :: 3 :: Only", +] + +dependencies = [ + "sphinx", + "sphinx_rtd_theme", + "myst_parser", + "sphinx-autobuild", + "linkify-it-py", + "sphinxcontrib-spelling", + "sphinx-reredirects", + "pytest", + "sphinxcontrib-mermaid" +] + +[project.optional-dependencies] +doc = [] +dev = [] + +[project.urls] +"Homepage" = "https://github.com/isiscomputinggroup/ibex_user_manual/" +"Bug Reports" = "https://github.com/isiscomputinggroup/ibex_user_manual/issues" +"Source" = "https://github.com/isiscomputinggroup/ibex_user_manual/" + +[tool.build_sphinx]