Skip to content

Commit f149aa4

Browse files
Tom-WillemsenTom-Willemsen
committed
Link genie_python commands through to the reference manual
1 parent 8a9c901 commit f149aa4

File tree

4 files changed

+95
-119
lines changed

4 files changed

+95
-119
lines changed

‎doc/scripting/Error-Checking-Troubleshooting.rst‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Error Checking Troubleshooting
55
Pylint
66
======
77

8-
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:
8+
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:
99

1010
.. code-block::
1111
@@ -102,9 +102,9 @@ Although wildcard imports are not recommended because of the possibility of name
102102
103103
You will still get a warning about wildcards which is good but not the warning about unused methods.
104104

105-
============
106-
New: Pyright
107-
============
105+
=======
106+
Pyright
107+
=======
108108

109109
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.
110110

@@ -118,7 +118,10 @@ Implications for Current and Future Scripts
118118

119119
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.
120120
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.
121+
121122
Examples of Common Pyright Errors
123+
---------------------------------
124+
122125
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.
123126

124127
**Example 1: Invalid Range**

‎doc/scripting/Matplotlib.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ The IBEX user interface includes a python scripting window. When plotting graphs
9191
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.
9292

9393
:::{note}
94-
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:
94+
If you prefer matplotlib windows to spawn separately from the main IBEX window, you can type the matplotlib command:
9595
```python
9696
matplotlib.use('Qt4Agg')
9797
```

‎doc/scripting/genie_python-Commands.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Genie Python Commands
2+
3+
## Running `genie_python` commands
4+
5+
When running python from an interactive console such as from
6+
the GUI, or after running `C:\Instrument\Apps\Python3\genie_python.bat`,
7+
the `genie` module will be aliased to `g`. Genie commands can then
8+
be accessed by using the prefix `g.[COMMAND_NAME]`. For example:
9+
10+
```python
11+
g.begin()
12+
g.cset("BLOCK_1", 1)
13+
g.abort()
14+
```
15+
16+
This is particularly useful from the GUI which will auto-complete
17+
commands and provide tool tips describing each function and its
18+
arguments.
19+
20+
For user or instrument scripts, the standard way of importing `genie_python` is:
21+
22+
```python
23+
from genie_python import genie as g
24+
```
25+
26+
Note that in many cases, arguments will be optional. For instance,
27+
{external+genie_python:py:obj}`g.begin <genie.begin>` can be used as `g.begin()`, despite additionally supporting optional
28+
arguments including `period`, `meas_id`, `meas_type`, `meas_subid`,
29+
`sample_id`, `delayed`, `quiet`, `paused`, and `verbose`.
30+
31+
## Common `genie_python` commands
32+
33+
Some commonly used `genie_python` commands are listed below.
34+
35+
This is **not a complete list**; For full information, consult the {external+genie_python:doc}`genie_python reference manual <genie_python>`.
36+
Click on a command name below to view the detailed documentation for that command in the reference manual.
37+
38+
### Starting and stopping a run
39+
40+
| Command | Description | Example |
41+
|-------------------------------------------------------|------------------------------------------|--------------|
42+
| {external+genie_python:py:obj}`begin <genie.begin>` | Starts a new run | `g.begin()` |
43+
| {external+genie_python:py:obj}`end <genie.end>` | Ends the current run (saving data) | `g.end()` |
44+
| {external+genie_python:py:obj}`abort <genie.abort>` | Aborts the current run (discarding data) | `g.abort()` |
45+
| {external+genie_python:py:obj}`pause <genie.pause>` | Pauses the current run | `g.pause()` |
46+
| {external+genie_python:py:obj}`resume <genie.resume>` | Resumes the current run after it has been paused | `g.resume()` |
47+
48+
### Updating blocks and PVs
49+
50+
| Command | Description | Example |
51+
|-------------------------------------------------------|--------------------------------------------------------------------|----------------------------------------|
52+
| {external+genie_python:py:obj}`cget <genie.cget>` | Gets the useful values associated with a block | `g.cget("NEW_BLOCK")` |
53+
| {external+genie_python:py:obj}`cset <genie.cset>` | Sets the setpoint, and optionally runcontrol settings, for a block | `g.cset("NEW_BLOCK",1)` |
54+
| {external+genie_python:py:obj}`get_pv <genie.get_pv>` | Gets the value of the specified PV | `g.get_pv("IN:INSTNAME:IOC_01:STAT")` |
55+
| {external+genie_python:py:obj}`set_pv <genie.set_pv>` | Sets the value of the specified PV | `g.set_pv("IN:INSTNAME:IOC_01:STAT",1)` |
56+
57+
### Run control
58+
59+
| Command | Description | Example |
60+
|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|
61+
| {external+genie_python:py:obj}`get_uamps <genie.get_uamps>` | Gets the number of micro-amp hours of beam collected in the current run | `g.get_uamps()` |
62+
| {external+genie_python:py:obj}`get_frames <genie.get_frames>` | Gets the number of {abbr}`good frames (Pulses which were counted, not counting any pulses that were ignored due to hardware vetoes or software run-control settings)` of beam collected in the current run | `g.get_frames()` || {external+genie_python:py:obj}`get_runstate <genie.get_runstate>` | Gets the current status of the instrument as a string | `g.get_runstate()` |
63+
| {external+genie_python:py:obj}`get_mevents <genie.get_mevents>` | Gets the total counts for all the detectors, in millions of events. | `g.get_mevents()` |
64+
| {external+genie_python:py:obj}`get_totalcounts <genie.get_totalcounts>` | Gets the total counts for all the detectors. | `g.get_totalcounts()` |
65+
| {external+genie_python:py:obj}`waitfor <genie.waitfor>` | Waits until certain conditions are met. | `g.waitfor("NEW_BLOCK",value=1)` |
66+
| {external+genie_python:py:obj}`waitfor_block <genie.waitfor_block>` | Waits until block reaches specific value. | `g.waitfor_block("NEW_BLOCK",1)` |
67+
| {external+genie_python:py:obj}`waitfor_time <genie.waitfor_time>` | Waits for a specified amount of time. | `g.waitfor_time(seconds=1)` |
68+
| {external+genie_python:py:obj}`waitfor_frames <genie.waitfor_frames>` | Waits for the number of total good frames collected in the current run to reach the specified total value. | `g.waitfor_frames(5000)` |
69+
| {external+genie_python:py:obj}`waitfor_uamps <genie.waitfor_uamps>` | Waits for the number of total uAmp-hours collected in the current run to reach the specified total value. | `g.waitfor_uamps(5.0)` |
70+
| {external+genie_python:py:obj}`waitfor_runstate <genie.waitfor_runstate>` | Waits for a particular instrument run state. | `g.waitfor_runstate("PAUSED")` |
71+
| {external+genie_python:py:obj}`waitfor_move <genie.waitfor_move>` | Waits for all motion, or specified motion axes, to complete. | `g.waitfor_move()` |
72+
73+
## Toggling options
74+
75+
Various options can be toggled using the {external+genie_python:py:obj}`genie_toggle_settings` module.
76+
77+
For example, toggling the verbosity of all calls to a command using {external+genie_python:py:obj}`toggle.cset_verbose(True) <genie_toggle_settings.cset_verbose>`. This can be convenient, as there will be no need to explicitly set `verbose=True` for each `cset` call.
78+
79+
There are also advanced options such as {external+genie_python:py:obj}`toggle.exceptions_raised(True) <genie_toggle_settings.exceptions_raised>`, which will allow exceptions to propagate instead of genie handling them, in case you want to handle exceptions yourself.
80+
81+
```{warning}
82+
If you have `exceptions_raised` toggled to True and there is an exception within `genie_python`, it will stop your script from running unless you catch the exception yourself.
83+
```
84+
85+
## Running in simulation mode
86+
87+
Genie_python supports a basic simulation mode; see {doc}`Simulating-Scripts` for how to use this.

0 commit comments

Comments
 (0)