Malcolm

Malcolm is a middlelayer framework that implements high level configure/run behaviour of control system components like those used in continuous scans. This repository contains a Python implementation (pymalcolm) allowing the creation of Malcolm servers and clients. There is also a malcolmjs JavaScript client and a Java client in GDA.

Malcolm was created as part of the Mapping project at Diamond Light Source in order to improve the performance of continuous scanning, providing a system that could scan arbitrary trajectories like spirals and grids within polygonal regions.

What can Malcolm do?

Malcolm provides a layer on top of EPICS that wraps up groups of PVs and presents a higher level scanning interface to GDA via pvAccess.

digraph malcolm_dls_usage { bgcolor=transparent node [fontname=Arial fontsize=10 shape=box style=filled fillcolor="#8BC4E9"] edge [fontname=Arial fontsize=10 arrowhead=vee] {rank=same;Detector EPICS "HDF File"} Malcolm [shape=doublecircle] GDA -> Malcolm [label="scan.configure()\nscan.run()"] Malcolm -> EPICS [label="caput\ncamonitor"] Detector -> EPICS [label="Frame data"] EPICS -> "HDF File" [label="Frame data"] EPICS -> "Motor Controller" [label="Motion trajectory"] }

Malcolm was developed for continuous scanning and the diagram above shows how Diamond uses it, but it can also be used in other ways:

  • As a library that can be used in continuous scanning scripts without acting as a server

  • As a webserver, exposing a web GUI for configuring the underlying hardware that communicates to Malcolm using JSON over websockets

  • As a distributed object system, using either pvAccess or websockets to communicate and synchronise objects between multiple Malcolm processes

How is the documentation structured?

The documentation is structured into a series of Tutorials and some general Reference documentation. End users and developers need different documentation, so links for various categories of user are listed below:

Configuring Malcolm to work with your hardware

Work through the Tutorials then look at the malcolm.modules API documentation to see what arguments need to be passed to each object in the YAML file.

Controlling Malcolm via comms protocols

Read the Hello World Tutorial, then look at the Block Structure and Message Structure sections. The malcolm.modules.pva module contains some pvAccess specific documentation. The RunnableStates statemachine will also be of interest.

Installation Guide

Using pipenv

We now use pipenv to generate the environment for Malcolm at Diamond. This should also work in any environment where pipenv is available.

First download the source code:

$ git clone https://github.com/DiamondLightSource/pymalcolm.git
$ cd pymalcolm

To be able to use Malcolm run:

$ pipenv install

For development you will need additional development packages:

$ pipenv install --dev

Then you can use the entry point to run Malcolm:

$ pipenv run imalcolm

Note: Malcolm is now installed as an editable module by default to make development easier.

Using pip

Otherwise you can install Malcolm using pip in any venv:

$ pip install malcolm

Which then gives you the entry point (assuming the venv is activated):

$ imalcolm