config_sessions.md 7.06 KB
Newer Older
1
2
# BLISS sessions

3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

## BLISS session

A *Session* groups BLISS objects defined in configuration under a single entity.

Such a group can reflect geographic characteristics (ex: *all devices of EH1*)
or functional characteristics (ex: *Spectrometers motors and counters*)

By default, *all objects* defined in beacon configuration will be loaded, then
the setup file is executed. To load only specific objects, the *YAML
configuration file* of the session must be adapted.

The *setup file* associated to a session is a Python script that is executed
after session objects are created. It can load user scripts and execute
user-defined functions.


## Launching a BLISS session

A session can be started in the *BLISS shell command line* with `-s` option:

```
% bliss -s eh1
```

```python
                       __         __   __
                      |__) |   | /__` /__`
                      |__) |__ | .__/ .__/


Welcome to BLISS version 0.02 running on pcsht (in bliss Conda environment)
Benoit Formet's avatar
Benoit Formet committed
35
Copyright (c) 2015-2020 Beamline Control Unit, ESRF
36
37
38
39
40
41
42
43
44
45
46
47
48
-
Connected to Beacon server on lid421 (port 3412)
eh1: Executing setup...
Initializing 'pzth'
Initializing 'simul_mca'
Initializing 'pzth_enc'
Hello eh1 session !!
Done.

EH1 [1]:
```


Sebastien Petitdemange's avatar
Sebastien Petitdemange committed
49
50
51
52
53
54
55
56
57
58
59
60
61
62
!!! note
    Two identical sessions cannot be started in a BLISS shell. This is
    ensured by usage of *Tmux* and by a locking mechanim. Tmux will display the
    previously started session instead of re-starting a new one. If Tmux is not
    used, an error message from the locking mechanism should appear at the
    second start of `demo` session:
    
    `demo is already running on host:pcsht,pid:8825 cmd: **bliss -s demo**`
    
    The error message gives all info needed to find where is running the previously
    started session and to deal with it (to kill it or to keep it).



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
## Files organization

The files used to configure a session are located in
`~/local/beamline_configuration/sessions/` directory.

```
 ~/local/beamline_configuration/
   ├── ...
   ├── sessions/
   .   ├── eh1.yml           <---- session configuration file
   .   ├── eh1_setup.py      <---- session setup file
       ├── __init__.yml
       └── scripts/
           ├── eh1_utils.py  <---- eh1 session related scripts
           |...
```

80
81

!!! note
82
83
    `__init__.yml` file contains `plugin: session` ; then, all YAML files in the
    directory are loaded using the Session plugin.
84

85
86
87
88
89
90
91
92
93

##  YAML Session configuration file

The file `~/local/beamline_configuration/sessions/<session_name>.yml` is used to
define for a session:

* the name of the session
* a list of objects to include or not in this session
* a list of measurment groups to include or not in this session
94
95
96

```yaml
- class: Session
97
98
99
  name: eh1
  setup-file: ./eh1_setup.py
  ...
100
101
```

102
103
104
105
106
107
The file `eh1.yml` defines a session called `eh1`, with a `eh1_setup.py` setup
file.

!! note
    The file path is relative to the session YAML file location if it starts
    with `./`, otherwise it is absolute from the root of the Beacon file database.
108

109
110
111
By default, **all objects** defined in the configuration will be loaded in the
session. It is possible to specify which objects must be included or not by
using the `config-objects` keyword with the list of object names:
112
113
114
115
116
117
118
119

```yaml
    - class: Session
      name: eh1
      setup-file: ./eh1_setup.py
      config-objects: [pzth, simul_mca]
```

120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
The list of objects can also be written as:
```yaml
    - class: Session
      name: eh1
      setup-file: ./eh1_setup.py
      config-objects:
        - pzth
        - simul_mca
```

Conversely, `exclude-objects` can be used to *not load* unused objects.


!!! note
    Sessions **can be nested** using `include-sessions`. This allows to have a
    session for a specific equipment, for example, and to be able to include
    the whole equipment and its setup in another session.


## Setup file
140

141
142
143
The *setup file* associated to a session (usualy
`~/local/beamline_configuration/sessions/<session_name>_setup.py`) is a Python
script that is executed after session objects are created.
144

145
146
147
All objects from the session are available in the setup script. The *globals*
defined in the setup script, and all session objects, are automatically added to
the `bliss.setup_globals` namespace, to be used in user scripts.
148
149
150
151
152
153
154
155
156
157

```py
import os
from bliss.common.standard import * # import all default functions, scans, etc.

SCAN_SAVING.base_path = os.path.join(os.environ["HOME"], "scans")
SCAN_SAVING.template = "{session}/{date}"
print "Setting scanfile to", SCAN_SAVING.get_path()
```

158
All objects can be made available in the session with:
159

160
161
162
```python
from bliss.setup_globals import *
```
163
164


165
166
167
168
169
170
## User scripts

Python files defined under the special `scripts/` directory can be loaded in the
setup file of a bliss session using the `load_script(<file_name>)` function.

All commands in the file are then executed.
171

172
173
174
In case of error, the `load_script()` function catches and displays exceptions,
but do not prevent the rest of the setup from executing. Each call to
`load_script` re-execute the commands again.
175

176
177
`load_script` is the equivalent of the `execfile` Python function, but for
session scripts.
178

179
180
181
182
183
184
185
186
!!! note
    
    User script located in session directory should be session-specific.
    
    Beamline specific should be placed in another directory to ease their maintenance.
    see: https://bliss.gitlab-pages.esrf.fr/ansible/local_code.html

### Example
187

188
The file is: `~/local/beamline_configuration/sessions/scripts/demo.py`
189

190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
```python

import time
# 'time' module is now usable in this file, but also in the session
# 'demo' after loading of the script.

print("[loading script]: align_spectrometer()")

def align_spectrometer(energy=5.0):
    print(f"Aligning spectrometer for energy {energy}...")
    time.sleep(1)
    print(f"Spectrometer is aligned :)")
```


Example of script loading and usage:

```python
DEMO [1]: load_script('demo')
[loading script]: align_spectrometer()
DEMO [2]:
DEMO [2]: align_spectrometer(energy=7.5)
Aligning spectrometer for energy 7.5  ...
Spectrometer is aligned :)
DEMO [3]:
```
216
217
218
219
220
221


## Automatic session creation

A skeleton of BLISS session can be created automatically with the `-c` option:

222
223
224
example for a session named `demo_session`
```
(bliss) pcsht:~ % bliss -c demo_session
225
Creating 'demo_session' BLISS session on BEACON_HOST=epilobe:25000
226
227
228
229
Creating sessions/demo_session.yml
Creating sessions/demo_session_setup.py
Creating sessions/scripts/demo_session.py
```
230
231
232

At start-up, the new session will display a message to help customization:

233
234
235
236
237
238
239
240
241
242
```
% bliss -c demo_session
[...]
Welcome to your new 'demo_session' BLISS session !!
You can now customize your 'demo_session' session by changing files:
   * .../demo_session_setup.py
   * .../demo_session.yml
   * .../scripts/demo_session.py
```

243
244
245

If a session already exists, it will not be erased or reset.

246
247
248
249
```
% bliss -c demo
Session 'demo' cannot be created: it already exists.
```
250
251
252

A session can be deleted with the `-d` option:

253
254
255
256
257
258
259
```
% bliss -d demo_session
Removing 'demo_session' session.
removing .../sessions/demo_session_setup.py
removing .../sessions/demo_session.yml
removing .../sessions/scripts/demo_session.py
```