Alignment: Phoebus update

Author: Kay Kasemir (ky9)

clean

@@ -0,0 +1,10 @@
+
+# Delete files generated by python and jython
+find . -name '*.class' -exec rm {} \;
+find . -name *.pyc -exec rm {} \;
+
+# Delete doc
+(cd doc; make clean)
+
+# Remove setup/bdist
+rm -rf build dist

doc/alignment_scan.png

@@ -1,5 +1,3 @@
-.. _scan_commands:
-
 Scan Commands
 =============
 

doc/commands.rst

@@ -9,84 +9,106 @@ Initial Setup
 We assume that you already have a recent version of EPICS base installed
 with access to commands like `softIoc`, `caget`, `caput`.
 
-Prepare the PyScanClient::
+Prepare the PyScanClient library and examples::
 
    git clone https://github.com/PythonScanClient/PyScanClient.git
    cd PyScanClient
    python setup.py build
+   export PYSCANCLIENT=`pwd`
 
-In here, we don't "install" the library
-but simply access it via the python path.
-In addition, we list the folder with examples to be used later
-in the path::
-
-   export PYTHONPATH=`pwd`/build/lib:`pwd`/example
+In here, we don't "install" the library but simply access it via the python path.
+In addition to the library, clients also need access to the examples,
+so we add both to the path used by C-Python::
+  
+   export PYTHONPATH=$PYSCANCLIENT/build/lib:$PYSCANCLIENT/example
 
 The scan server is a CS-Studio service.
 Both the scan server and the CS-Studio GUI can be built
 from https://github.com/ControlSystemStudio/phoebus.
 More convenient binaries are available from
 https://controlssoftware.sns.ornl.gov/css_phoebus/nightly/
 
-Create a settings file for CS-Studio that holds the path to
-this python library::
-
-    echo org.csstudio.display.builder.runtime/python_path=$PYTHONPATH >>my_settings.ini
-
-You may also add common settings like CA or PVA address lists
-to that file, or add the `..runtime/python_path` setting to
-an already existing local settings file.
-
-All CS-Studio tools are based on Java. The CS-Studio GUI binary
-may bundle a java runtime. If it includes a `jdk` folder, use that.
-Otherwise fetch a Java runtime from https://jdk.java.net
+All CS-Studio tools are implemented in Java. Some CS-Studio GUI binaries
+bundle a java runtime. If it includes a `jdk` folder, use that.
+Otherwise fetch a Java runtime from https://jdk.java.net.
 Either way, declare your JDK and add its `bin` folder to the PATH::
 
   export JAVA_HOME=/path/to/jdk
   export PATH=$JAVA_HOME/bin:$PATH
   java -version
 
+Both the scan server and the CS-Studio GUI likely need to access
+the same PVs, so you can create a common `my_settings.ini` for them.
+In here we start with just localhost::
+
+   echo org.phoebus.pv.ca/addr_list=127.0.0.1 >>my_settings.ini
+
+For more on PV related settings, see
+https://control-system-studio.readthedocs.io/en/latest/preference_properties.html#pv
+
+For the CS-Studio displays, we add the path to this python library and its examples::
+
+    echo org.csstudio.display.builder.runtime/python_path=$PYTHONPATH >>my_settings.ini
+
+This `.../python_path` setting is for CS-Studio displays to locate display scripts.
+It is not required by the scan server, but for simplicity
+you may combnied settings in a common file loaded by all CS-Studio tools,
+since the tools will ignore settings that don't apply to them.
+
+The scan server uses an additional configuration file.
+For a full example see https://github.com/ControlSystemStudio/phoebus/blob/master/services/scan-server/src/main/resources/examples/scan_config.xml
+
+For these tests we use a simpler file based on this template
+to primarily set the path used by server-side scripts:
+
+.. literalinclude:: ../example/server/scan_config_template.xml
+
+Based on that template, create the file for your PyScanClient example path::
+
+   cat $PYSCANCLIENT/example/server/scan_config_template.xml |
+   sed -e "s#<path>.*#<path>$PYSCANCLIENT/example/server</path>#" >my_scan_config.xml
+
 Assuming you fetched a scan server binary, start the scan server like this::
 
    unzip scan-server.zip
    rm scan-server.zip
    cd scan-server-*
-   ./scan-server.sh
-
+   ./scan-server.sh -settings /path/to/my_settings.ini -config /path/to/my_scan_config.xml
+   
 On success, note the REST URL and list of console commands::
 
-   INFO ../ Scan Server (PID 1766187)
+   INFO ... Scan Server (PID 1766187)
    INFO ... Scan Server REST interface on http://localhost:4810/index.html
    Scan Server Commands:
    help            -  Show commands
    ...
    shutdown        -  Stop the scan server
 
-You would stop the scan server by typing `shutdown`, then restart via `scan-server.sh`.
+You would stop the scan server by typing `shutdown`, then restart as just shown.
 
 
 Test Beamline
 -------------
 
-Subsequent sections use a simple test beamline created by `simulation.db`.
+Subsequent sections use a test beamline created by `simulation.db`.
 The scan GUIs use additional databases.
 Start them all in one IOC like this::
 
-   cd PyScanClient/example
-   softIoc -m S=Demo -d ioc/simulation.db -d ioc/table.db
+   cd $PYSCANCLIENT/example/ioc
+   softIoc -m S=Demo -d simulation.db -d table.db -d range.db -d fit.db
 
 Assuming you fetched a binary for CS-Studio, start the associated GUI like this::
 
    unzip phoebus-linux.zip
    rm phoebus-linux.zip
    cd phoebus-*/
-   ./phoebus.sh -settings /path/to/my_settings.ini -resource /path/to/PyScanClient/example/opi/1_BeamLine.bob
+   ./phoebus.sh -settings /path/to/my_settings.ini -resource $PYSCANCLIENT/example/opi/1_BeamLine.bob
 
 .. image:: simulation.png
 
 Familiarize yourself with the simulation.
 
-* The "Beam" is mostly on, but occasionally turns off.
+* The "Beam" is mostly on, but turns itself off for brief periods.
 * Click on the "Shutter" to open or close it.
   While beam is on and the shutter open, the "Neutrons" counter increments.
   The "Proton Charge" increments as well, but you may
@@ -111,11 +133,11 @@ but point your web browser to http://localhost:4810 and try the following.
   some control system operator interface host to http://name_of_server:4810
   to check network connectivity to the scan server.
 * Follow the "/server/info" link.
-  The XML format of the information is obviously not perfect for
+  The XML format of the information is obviously not meant for
   interactive use. For example, you would have to convert a UNIX epoch
   start time of "1711118742626" into "2024-03-22 10:45:42 EDT" to verify
   the scan server start time,
-  but if all else fails such direct REST access can help you debug
+  but if all else fails such direct REST access can help you to debug
   your setup on a low level.
 * Back from the start page http://localhost:4810, click the
   "/scan/{name-of-new-scan}" link for submitting a new scan.
@@ -150,14 +172,14 @@ Scan Server Console
   "/scan/{name-of-new-scan}" link and submit anoter example scan.
 
 
-CS-Studio GUI
--------------
+CS-Studio GUI Scan Tools
+------------------------
 
 * In CS-Studio, invoke the menu Applications, Scan, Scan Monitor.
   You should see the last submitted scan as "Finished-OK",
   the others as simply "Logged".
 * Right-click on any scan and open the "Data Table".
-* Right-click no the "Finished" scan and open the "Scan Editor".
+* Right-click on the "Finished" scan and open the "Scan Editor".
 * In the scan editor, right-click to "Submit scan".
   It submits the same commands once more. While the scan is executing,
   the scan editor highlights the active command in green.
@@ -166,35 +188,34 @@ CS-Studio GUI
 .. image:: scan_monitor_editor.png
 
 * In the scan editor, create a list of "Delay 1 sec" commands by deleting everything else,
-  dragging noe "Delay" command from th palette into the editor,
+  dragging one "Delay" command from the palette into the editor,
   then use copy/paste from the context menu or Control-drag-drop to
   create about 10 delays.
 * Submit the scan and note how it highlights the active delay command.
   Use the "pause" button in either the scan monitor or editor to pause and then resume
   the commands.
 * Quickly submit the scan multiple times from the scan editor.
   Use the "Re-submit Scan" entry from the scan monitor context menu.
-  Note how one scan executes, and additional scans are queued up to
+  Note how one scan executes, and additional scans queue up to
   be executed next. Idle scans can be moved up or down in the list of queued
   scans, or aborted.
-* In the scan monitor, selet a few older scans, right-click on them and "Remove selected". 
+* In the scan monitor, select a few older scans, right-click on them and "Remove selected". 
 
-The scan monitor is very useful to monitor
-the progress of queued and active scans.
+The scan monitor is very useful to track the progress of queued and active scans.
 
 The scan editor could be used to manually assemble small scans,
 but it's mainly meant to debug scans that have been submitted by other means.
 
 The scan server will hold the commands of past scans in memory
 and persist the logged data on disk, but this
 is all meant to debug scans, not to replace data aquisition.
-Based on memory usage thresholds, the scan server will automatically change
-in-memory scans to only logged scans.
+Based on memory usage thresholds, the scan server will automatically reduce
+in-memory scans to logged scans.
 While the scan monitor can list many scans, reading the list of scans from
-the server and displaying it will use noticable CPU once there are 10000 and more
-scans in the list.
+the server and displaying it in the GUI will use noticable CPU once there are
+10000 and more scans in the list.
 Periodically, for example when a new series of experiments start,
-it is thus suggested to manually remove information for older scans,
+it is thus suggested to manually remove older scans,
 either by deleting selected scans or by invoking "Remove completed scans"
 from the scan monitor context menu.
 
@@ -212,31 +233,30 @@ and run it::
 .. literalinclude:: ../example/commands1.py
 
 Note how the python script assembles a list of commands.
-It builds the recipe for one "scan", submits it to the scan server,
-and exits.
+It builds the recipe, submits it to the scan server, and exits.
 The scan server then spends more than a minute to execute the submitted
 commands.
 
 In the CS-Studio scan monitor, right-click on the running scan to open
 the "Scan Data Table" and watch how samples are added.
 This internal data logger is again not meant to replace data aquisition,
-but meant to assist in tracknig the progress of scans and to debug them.
+but assists in tracking the progress of scans.
 
-At this point you may familiarize yourself with all the :ref:`scan_commands`,
+At this point you may familiarize yourself with all the :doc:`scan commands <commands>`,
 especially the many options of the :class:`.Set` command.
-The PyScanClient `tutorial` folder contains several examples
-to try.
+The PyScanClient `tutorial` folder contains several more example scripts.
 
 
 Default Device Settings
 -----------------------
 
-A command to turn a power supply on or set a voltage may be instantaneous::
+The command to set a power supply voltage may be instantaneous::
 
-    commands = [ Set('PS42:Voltage', 12.0), Comment("PS is now on at 12 Volts")]
+    commands = [ Set('PS42:Voltage', 12.0),
+                 Comment("PS is now on at 12 Volts") ]
 
 But this device behavior tends to be the exception.
-When controlling a motor, the EPICS motor support allows using a "put-callback"
+When controlling a motor, the EPICS motor support allows a "put-callback"
 to the device which waits until the motor reaches the desired location.
 This mechanism is also referred to as "completion".
 A temperature controller might support completion on its temperature
@@ -256,7 +276,7 @@ Unfortunately, the "correct" way to set a PV is not discernible from the outside
 It requires knowledge about the implementation of a PV in the IOC.
 And even if the correct way to set a PV is known, having to type
 all parameters for each `Set` command can be cumbersone.
-The PyScanClient :ref:`scan_settings` provide a way to configure default parameters
+The PyScanClient :doc:`scan settings <scan_settings>` provide a way to configure default parameters
 for each PV.
 Wrappers for the basic `Set`, `Loop` and `Wait` commands then use these defaults.
 For an example, see `example/beamline_setup.py`:
@@ -366,6 +386,19 @@ without manual conversion to CSV.
 Alignment Scan
 -------------- 
 
+One fairly common beamline procedure is the alignment.
+For example, a slit or sample is moved across a range of positions,
+the intensity of a signal is noted at each position,
+and we try to locate the maximum of that signal.
+
+In CS-Studio, use the menu `File`, `Open` to open
+`PyScanClient/example/opi/1_BeamLine.bob`
+and in there set the "Y" motor to 3.0.
+Now open `PyScanClient/example/opi/4_Alignment_Scan.bob`.
+Adjust the settings as shown the following screenshot, then press "Submit".
+
+.. image:: alignment_scan.png
+
 TODO
 Custom script commands
 
@@ -380,4 +413,5 @@ Both the scan server and the CS-Studio GUI are typically started by a site-speci
 launcher script that adds `-settings /path/to/site/settings.ini`.
 
 
-TODO: scan server's pre and post commands
+TODO: scan server's pre and post commands
+

doc/getting_started.rst

@@ -36,5 +36,5 @@ Use Case: Custom Python Scripts
 -------------------------------
 
 Finally, custom Python scripts can assemble a set of commands,
-see :ref:`scan_client`
-and :ref:`scan_commands`.
+see :doc:`scan client <scan_client>`
+and :doc:`scan commands <commands>`.

doc/overview.rst

@@ -1,5 +1,3 @@
-.. _scan_client:
-
 Scan Client
 ===========
 

doc/scan_client.rst

@@ -1,5 +1,4 @@
 
-
 .. automodule:: scan.util.scan_settings
    :members:
 

doc/scan_settings.rst

@@ -1,49 +1,40 @@
 """Example for beamline specific setup
-
-   All scripts that access the scan server
-   should start with
+   All scripts that access the scan server should start with
 
      'from beamline_setup import *'
 """
 
 # Get all scan commands
 from scan import *
-
-# Replace basic Loop/Set/Wait commands with wrappers
-# that utilize custom scan settings
+# Replace basic Loop/Set/Wait commands with wrappers that use scan settings
 from scan.util import SettingsBasedLoop as Loop
 from scan.util import SettingsBasedSet as Set
 from scan.util import SettingsBasedWait as Wait
 
-# Each "beamline" or more generally setup that uses
-# the PyScanClient should create its own ScanSettings 
+# Implement ScanSettings for this beamline 
 class BeamlineScanSettings(ScanSettings):
     def __init__(self):
         super(BeamlineScanSettings, self).__init__()
 
-        # Define settings based on PV name patterns
-        # (regular expressions).
-        # Order matters! List most generic patterns first,
-        # specific PV names last.
-        # For example, motors should use completion, and check a readback
+        # Define settings based on PV name patterns (regular expressions).
+        # Order matters! List patterns first, specific PVs last.
+        # In general, motors should use completion, and check a readback
         self.defineDeviceClass("motor_.", completion=True, readback=True)
         # The specific motors in the simulation.db, however, don't support completion
         self.defineDeviceClass("motor_x", completion=False, readback=False)
         self.defineDeviceClass("motor_y", completion=False, readback=False)
         self.defineDeviceClass("shutter", readback=True)
-        # The simulated "setpoint" uses a different PV "readback" as its readback.
-        # (readback=False skips readback check
-        #  readback=True calls getReadbackName(pv) which typically returns the PV itself,
-        #  readback='whatever' uses provided PV
-        # )
+        # The simulated "setpoint" uses a different "readback" PV as its readback.
+        # readback=False skips readback check
+        # readback=True calls getReadbackName(pv) which typically returns the PV itself
+        # readback='whatever' uses provided PV
         self.defineDeviceClass("setpoint", completion=False, readback="readback", tolerance=0.1, timeout=20)
         # When waiting for proton charge or neutron counts, use "increase by"
         self.defineDeviceClass("pcharge", comparison="increase by")
         self.defineDeviceClass("neutrons", comparison="increase by")
 
         # Each site may add more to its site-specific configuration.
-        # The example/opi for alignment uses these to
-        # populate drop-downs
+        # The example/opi for alignment uses these to populate drop-downs
         self.settable = [ "motor_x", "motor_y" ]
         self.waitable = [ "seconds", "time", "pcharge" ]
         self.loggable = [ "signal" ]
@@ -112,4 +103,4 @@ def table_scan(headers, rows):
     print("")
     print("Scan Client")
     print("===========")
-    print(scan_client)
+    print(scan_client)