Commit 24a291a0 authored by Michal Maciejewski's avatar Michal Maciejewski
Browse files

Updated README.md

parent d0ffdb8a
<h1><center>Analysis of an FPA in an 600A Circuit</center></h1>
The 600-A circuits come in one of two main variants:
- circuits with
- and without EE.
Each variant may or may not be equipped with a DC contactor ensuring the effectiveness of the crowbar in case of a PC short circuit. Moreover, the magnets of several circuits are equipped with parallel resistors, in order to decouple the current decay in a quenching magnet from that in the rest of the circuit. Figure 1 shows a generic circuit diagram, equipped with EE and parallel resistor, as well as lead resistances and a quench resistance.
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/600A/600A.png" width=75%>
source: Test Procedure and Acceptance Criteria for the 600 A Circuits, MP3 Procedure, <a href="https://edms.cern.ch/document/874716/5.3">https://edms.cern.ch/document/874716/5.3</a>
Table below provides a list of circuits to be used with these analysis notebooks
|RCBX family|RCD/O family|Remaining 600A circuits with EE|Remaining 600A circuits without EE|
|-----------|------------|-------------------------------|----------------------------------|
|RCBXH1|RCD|RCS|RQS (RQS.L)|
|RCBXH2|RCO|RSS|RQSX3|
|RCBXH3| |ROD|RQT12|
|RCBXV1| |ROF|RQT13|
|RCBXV2| |RQTL9|RQTL7|
|RCBXV3| |RQS (RQS.A)|RQTL8|
| | |RQTD|RQTL10|
| | |RQTF|RQTL11|
| | |RSD1|
| | |RSD2|
| | |RSF1|
| | |RSF2|
| | |RU|
Another useful resource to find out which 600 A circuits belong to which category is the circuit tree on the MP3 website http://cern.ch/mp3
......@@ -3,54 +3,18 @@
# Notebooks for Circuit Analysis of HWC Tests and Events during Operation
Although, as the project name indicates, our primary goal is the development of signal monitoring applications, we realized that the analysis modules developed so far can be pieced together into HWC test and operation analysis notebooks.
Even though, we develop the analyses system by system, they were developed in a general way to account for all circuits in which the system was present. Thus, by taking a perpendicular view of the analysis table, a circuit analysis for this stance was possible.
![Monitoring vs HWC](figures/monitoring-vs-hwc.png)
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/monitoring-vs-hwc.png" width=50%>
In particular, thotebooks are suited for HWC tests:
- can be adjusted on-the-fly for new requirements while performing a test;
- can immediately generate a report for storage and distribution among a team of domain experts;
- provide a sequential way of testing each system in a given order.
# Prerequsities
The execution of notebooks is carried out with SWAN service (http://swan.cern.ch) and requires three steps:
1. NXCALS Access (done only)
2. Setting up an appropriate environment script (done at each login)
3. Running an appropriate notebook
## 1. NXCALS Access
The NXCALS database requires an assignment of dedicated access rights for a user.
If you want to query NXCALS with the API, please follow a procedure below on how to request the NXCALS access.
1. Go to http://nxcals-docs.web.cern.ch/current/user-guide/data-access/nxcals-access-request/ for most updated procedure
2. Send an e-mail to mailto:acc-logging-support@cern.ch with the following pieces of information:
- your NICE username
- system: WinCCOA, CMW
- NXCALS environment: PRO
Optionally one can mention that the NXCALS database will be accessed through SWAN.
Once the access is granted, you can use NXCALS with SWAN.
## 2. Setting an Environment Script
In order to execute the HWC notebooks, one requires `lhc-sm-api` package and HWC notebooks. To this end, we created a dedicated environment script to prepare the SWAN project space.
The script sets a path to a virtual environment with the necessary packages (for more details, cf. https://lhc-sm-api.web.cern.ch/lhc-sm-api/user_install.html#preinstalled-packages) as well as makes a copy of HWC notebooks to `hwc` notebooks. **Note that in order to ensure compatibility between package and notebook versions, the `hwc` folder is deleted each time the script is executed'.**
Firstly, contact the Signal Monitoring team (mailto:lhc-signal-monitoring@cern.ch) in order to get read access to the EOS folder with pre-installed packages and HWC analysis notebooks.
Once the access is granted, at every log-in to SWAN, please provide the following environment script:
`/eos/project/l/lhcsm/public/packages_notebooks.sh`
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/swan_environment_script.png" width=25%>
Note the following settings while configuring environment:
- Software stack: `NXCals Python3`
- Platform: `CentOS 7 (gcc7)` - default
- Environment script: `/eos/project/l/lhcsm/public/packages_notebooks.sh`
- Number of cores: `4`
- Memory: `16`
- Spark cluster: `BE NXCALS (NXCals)`
%% Cell type:markdown id: tags:
# Supported Circuits
## 1. RB - Main Dipole Circuit
<img src = "https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/rb/RB.png" width=75%>
......@@ -91,103 +55,104 @@
|HWC|PNO.b3|I\_PNO+I\_DELTA|Energy Extraction from QPS|[AN\_RQ\_PNO.b3](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PNO.b3.ipynb)|[AN\_RQ\_PNO.b3](https://sigmon.web.cern.ch/node/71)|
|HWC|PNO.a6|I\_PNO|Current cycle to I\_PNO|[AN\_RQ\_PNO.a6](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PNO.a6.ipynb)|[AN\_RQ\_PNO.a6](https://sigmon.web.cern.ch/node/70)|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_RQ\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_FPA.ipynb)|[AN\_RQ\_FPA](https://sigmon.web.cern.ch/node/60)|
## 3. 600A Circuits
The 600-A circuits come in one of two main variants:
- circuits with
- and without EE.
Each variant may or may not be equipped with a DC contactor ensuring the effectiveness of the crowbar in case of a PC short circuit. Moreover, the magnets of several circuits are equipped with parallel resistors, in order to decouple the current decay in a quenching magnet from that in the rest of the circuit. Figure 1 shows a generic circuit diagram, equipped with EE and parallel resistor, as well as lead resistances and a quench resistance.
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/600A/600A.png" width=75%>
source: Test Procedure and Acceptance Criteria for the 600 A Circuits, MP3 Procedure, <a href="https://edms.cern.ch/document/874716/5.3">https://edms.cern.ch/document/874716/5.3</a>
Table below provides a list of circuits to be used with these analysis notebooks
|RCBX family|RCD/O family|Remaining 600A circuits with EE|Remaining 600A circuits without EE|
|-----------|------------|-------------------------------|----------------------------------|
|RCBXH1|RCD|RCS|RQS (RQS.L)|
|RCBXH2|RCO|RSS|RQSX3|
|RCBXH3| |ROD|RQT12|
|RCBXV1| |ROF|RQT13|
|RCBXV2| |RQTL9|RQTL7|
|RCBXV3| |RQS (RQS.A)|RQTL8|
| | |RQTD|RQTL10|
| | |RQTF|RQTL11|
| | |RSD1|
| | |RSD2|
| | |RSF1|
| | |RSF2|
| | |RU|
%% Cell type:markdown id: tags:
Another useful resource to find out which 600 A circuits belong to which category is the circuit tree on the MP3 website http://cern.ch/mp3
# User Guide
|Type|Test|Current|Description|Notebook|Example report|
|----|----|-------|-----------|--------|--------------|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_600A\_with\_without\_EE\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/600A/AN_600A_with_without_EE_FPA.ipynb)|-|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_600A\_RCDO\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/600A/AN_600A_RCDO_FPA.ipynb)|-|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_600A\_RCBXHV\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/600A/AN_600A_RCBXHV_FPA.ipynb)|-|
%% Cell type:markdown id: tags:
## Getting Started with SWAN
SWAN (Service for Web-based ANalysis) is an internal service at CERN provided by the IT department. It is an execution environment accessible through modern internet browser (http://swan.cern.ch).
# User Guide
The execution of notebooks is carried out with SWAN service (http://swan.cern.ch) and requires three steps:
1. Getting NXCALS Access (once only)
2. Logging to SWAN
3. Setting up an appropriate environment script (done at each login)
4. Running an appropriate notebook
### 1. Getting NXCALS access for SWAN
Our notebooks query signals from PM and NXCALS. The NXCALS database requires an assignment of dedicated access rights for a user. A procedure below describes how to the NXCALS request access.
1. Go to http://nxcals-docs.web.cern.ch/current/user-guide/data-access/nxcals-access-request/ for most updated procedure
2. Send an e-mail to mailto:acc-logging-support@cern.ch with the following pieces of information
- your NICE username
- system: WinCCOA, CMW
- NXCALS environment: PRO
- Optionally one can mention that the NXCALS database will be accessed through SWAN
## 1. NXCALS Access
The NXCALS database requires an assignment of dedicated access rights for a user.
If you want to query NXCALS with the API, please follow a procedure below on how to request the NXCALS access.
Once the access is granted, please proceed with the following steps.
1. Go to http://nxcals-docs.web.cern.ch/current/user-guide/data-access/nxcals-access-request/ for most updated procedure
2. Send an e-mail to mailto:acc-logging-support@cern.ch with the following pieces of information:
- your NICE username
- system: WinCCOA, CMW
- NXCALS environment: PRO
Optionally one can mention that the NXCALS database will be accessed through SWAN.
Once the access is granted, you can use NXCALS with SWAN.
### 2. Accessing SWAN
## 2. Logging to SWAN
The following steps should be followed in order to log-in to SWAN
1. Go to http://swan.cern.ch
2. Login with your NICE account
- SWAN is tightly integrated with CERNBox service (in fact, files created in SWAN are accessible in CERNBox). In case you have not used CERNBox, the following error message will be displayed in- dicating that your CERNBox account has not been activated yet. In order to activate your CERNBox account, please login on the website: http://cernbox.cern.ch. Afterwards, please login to SWAN service again. In case the error persists, please contact the SWAN support (cf. Chapter 3).
### 3. Selecting SWAN Environment Configuration
SWAN supports a range of software distributions. In order to execute LHC-SM quench analysis notebooks, a specific SWAN configuration has to be selected as shown below.
![SWAN Inactive CERNBox Error](figures/swan-inactive-cernbox-error.png)
A summary of recommended settings is provided in figure and table below.
|Parameter|Value|
|---------|-----|
|Software stack|NXCals Python3|
|Platform|CentOS 7 (gcc8)|
|Environment script|-|
|Number of cores|4|
|Memory|10|
|Spark cluster|BE NXCALS (NXCals)|
![SWAN Configure Environment](figures/swan-configure-environment.png)
After setting these parameters, please click [Start my Session] button. If you login for the first time, the project space is empty.
![SWAN Empty Project Space](figures/swan-empty-project-space.png)
%% Cell type:markdown id: tags:
# Notebook Upload
In order to upload an analysis notebook for the RB circuit, please follow the steps outlined below.
1. Go to LHC-SM GitLab project at https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/ tree/1.1.0/hwc/rb and select a notebook to download (for RQ, please visit: https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/tree/1.1.0/hwc/rq). You should see a notebook viewer as shown below.
![GitLab download](figures/gitlab-download.png)
2. Click the download icon as shown in Figure above.
3. Go to your SWAN space and create a new project (e.g., lhc-sm-apps) by clicking plus button indicated in Figure below.
![SWAN create new project](figures/swan-create-new-project.png)
4. Go to the new project by clicking its name.
5. Create a new folder for the quench analysis notebook by clicking + button and selecting Folder; see Figure below.
![SWAN create new folder](figures/swan-create-new-folder.png)
By default, a new folder is named ’Untitled Folder’. Please rename the folder to ’hwc’. To do so, select the folder and click rename button as shown in Figure below.
- SWAN is tightly integrated with CERNBox service (in fact, files created in SWAN are accessible in CERNBox). In case you have not used CERNBox, the following error message will be displayed in- dicating that your CERNBox account has not been activated yet. In order to activate your CERNBox account, please login on the website: http://cernbox.cern.ch. Afterwards, please login to SWAN service again. In case the error persists, please contact the SWAN support (see Section Help and Feedback at the bottom).
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/swan-inactive-cernbox-error.png" width=50%>
![SWAN rename folder](figures/swan-rename-folder.png)
## 3. Setting an Environment Script
In order to execute the HWC notebooks, one requires `lhc-sm-api` package and HWC notebooks. To this end, we created a dedicated environment script to prepare the SWAN project space.
The script sets a path to a virtual environment with the necessary packages (for more details, cf. https://lhc-sm-api.web.cern.ch/lhc-sm-api/user_install.html#preinstalled-packages) as well as makes a copy of HWC notebooks to `hwc` notebooks. **Note that in order to ensure compatibility between package and notebook versions, the `hwc` folder is deleted each time the script is executed'.**
Firstly, contact the Signal Monitoring team (mailto:lhc-signal-monitoring@cern.ch) in order to get read access to the EOS folder with pre-installed packages and HWC analysis notebooks.
6. Click ’hwc’ folder to enter it.
7. Inside the ’hwc’ folder create another one and name it ’rb’.
8. Click ’rb’ folder to enter it (for the RQ circuit, create rq folder accordingly).
9. Click upload icon in order to upload the hwc_rb_PM_RB_FPA.ipynb notebook.
Once the access is granted, at every log-in to SWAN, please provide the following environment script:
`/eos/project/l/lhcsm/public/packages_notebooks.sh`
![SWAN upload notebook](figures/swan-upload-notebook.png)
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/swan_environment_script.png" width=25%>
10. First rename the notebook to PM_RB_FPA.ipynb by removing the suffix ’hwc_rb_’ and then click the [Upload] button.
Note the following settings while configuring environment:
- Software stack: `NXCals Python3`
- Platform: `CentOS 7 (gcc7)` - default
- Environment script: `/eos/project/l/lhcsm/public/packages_notebooks.sh`
- Number of cores: `4`
- Memory: `16`
- Spark cluster: `BE NXCALS (NXCals)`
![SWAN rename notebook](figures/swan-rename-notebook.png)
## 4. Running Notebook
### 4.1. Open notebook
11. Open notebook by clicking its name. The top of the notebook is presented in Figure below.
To do so simply click its name and a new page will be opened. The top of the notebook is presented in Figure below.
![SWAN RB FPA analysis intro](figures/swan-rb-fpa-analysis-intro.png)
%% Cell type:markdown id: tags:
#### 4.2 Connection to the NXCALS Cluster
### 4.2. Connect to the NXCALS Spark Cluster
Once a notebook is opened, please click a star button as shown in Figure below in order to open the Spark cluster configuration in a panel on the right side of an active notebook.
![SWAN Open Spark Cluster Configuration](figures/swan-open-spark-cluster-configuration.png)
Figure below shows a three-step procedure of Spark cluster connection. The first step involves providing the NICE account password. The second step allows setting additional settings for the connection. In order to connect with NXCALS please make sure to enable the following options:
......@@ -196,13 +161,11 @@
The last step is a confirmation of a successful connection to the cluster.
![SWAN Spark Cluster Connection](figures/swan-spark-cluster-connection.png)
%% Cell type:markdown id: tags:
#### 3. Analysis Notebook Execution
### 4.3. Analysis Notebook Execution
A notebook is composed by cells. A cell contains either a markdown text with description or python code toexecute. Cells with markdown text have white background and can contain text, tables, figures, and hyperlinks.Cells with code have gray background and are executed by clicking a run icon in the top bar highlighted in Figure below. Alternatively, one can put a cursor in a cell with code an press a keyboard shortcut Ctrl+Enter.
![SWAN Execute Cell](figures/swan-execute-cell.png)
A state of a cell is indicated by square brackets located on the left to a cell. Execution of a cell is indicatedby a star in the square brackets. Once cell execution is completed the star changes into a number representingthe order of cell execution. A cell can execute for too long due to connection problems, issues with a databasequery, kernel problems. In this case, two actions are recommended:
......
......@@ -3,7 +3,7 @@ Although, as the project name indicates, our primary goal is the development of
Even though, we develop the analyses system by system, they were developed in a general way to account for all circuits in which the system was present. Thus, by taking a perpendicular view of the analysis table, a circuit analysis for this stance was possible.
![Monitoring vs HWC](figures/monitoring-vs-hwc.png)
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/monitoring-vs-hwc.png" width=50%>
In particular, thotebooks are suited for HWC tests:
- can be adjusted on-the-fly for new requirements while performing a test;
......@@ -18,7 +18,7 @@ In particular, thotebooks are suited for HWC tests:
|Type|Test|Current|Description|Notebook|Example report|
|----|----|-------|-----------|--------|--------------|
|HWC|PIC2|I\_MIN\_OP|Interlock tests with PC connected to the leads|[AN\_RB\_PIC2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rb/AN_RB_PIC2.ipynb)|[AN\_RB\_PIC2](https://sigmon.web.cern.ch/node/47)|
|HWC|PIC2|I_MIN_OP|Interlock tests with PC connected to the leads|[AN\_RB\_PIC2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rb/AN_RB_PIC2.ipynb)|[AN\_RB\_PIC2](https://sigmon.web.cern.ch/node/47)|
|HWC|PLI1.a2|I\_INJECTION|Current cycle to I\_INJECTION|[AN\_RB\_PLI1.a2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rb/AN_RB_PLI1.a2.ipynb)|[AN\_RB\_PLI1.a2](https://sigmon.web.cern.ch/node/48)|
|HWC|PLI1.b2|I\_INJECTION|Energy Extraction from QPS|[AN\_RB\_PLI1.b2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rb/AN_RB_PLI1.b2.ipynb)|[AN\_RB\_PLI1.b2](https://sigmon.web.cern.ch/node/49)|
|HWC|PLI1.d2|I\_INJECTION|Unipolar Powering Failure|[AN\_RB\_PLI1.d2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rb/AN_RB_PLI1.d2.ipynb)|[AN\_RB\_PLI1.d2](https://sigmon.web.cern.ch/node/50)|
......@@ -39,7 +39,7 @@ In particular, thotebooks are suited for HWC tests:
|Type|Test|Current|Description|Notebook|Example report|
|----|----|-------|-----------|--------|--------------|
|HWC|PIC2|I\_MIN\_OP|Powering Interlock Controller|[AN\_RQ\_PIC2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PIC2.ipynb)|[AN\_RQ\_PIC2](https://sigmon.web.cern.ch/node/61)|
|HWC|PIC2|I_MIN_OP|Powering Interlock Controller|[AN\_RQ\_PIC2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PIC2.ipynb)|[AN\_RQ\_PIC2](https://sigmon.web.cern.ch/node/61)|
|HWC|PLI1.b3|I\_INJECTION|Energy Extraction from QPS|[AN\_RQ\_PLI1.b3](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PLI1.b3.ipynb)|[AN\_RQ\_PLI1.b3](https://sigmon.web.cern.ch/node/62)|
|HWC|PLI1.d2|I\_INJECTION|Unipolar Powering Failure|[AN\_RQ\_PLI1.d2](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PLI1.d2.ipynb)|[AN\_RQ\_PLI1.d2](https://sigmon.web.cern.ch/node/63)|
|HWC|PLI2.s1|I\_INTERM\_1|Splice Mapping|[AN\_RQ\_PLI2.s1](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PLI2.s1.ipynb)|[AN\_RQ\_PLI2.s1](https://sigmon.web.cern.ch/node/65)|
......@@ -52,141 +52,99 @@ In particular, thotebooks are suited for HWC tests:
|HWC|PNO.a6|I\_PNO|Current cycle to I\_PNO|[AN\_RQ\_PNO.a6](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_PNO.a6.ipynb)|[AN\_RQ\_PNO.a6](https://sigmon.web.cern.ch/node/70)|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_RQ\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/rq/AN_RQ_FPA.ipynb)|[AN\_RQ\_FPA](https://sigmon.web.cern.ch/node/60)|
# User Guide
## Getting Started with SWAN
SWAN (Service for Web-based ANalysis) is an internal service at CERN provided by the IT department. It is an execution environment accessible through modern internet browser (http://swan.cern.ch).
### 1. Getting NXCALS access for SWAN
Our notebooks query signals from PM and NXCALS. The NXCALS database requires an assignment of dedicated access rights for a user. A procedure below describes how to the NXCALS request access.
1. Go to http://nxcals-docs.web.cern.ch/current/user-guide/data-access/nxcals-access-request/ for most updated procedure
2. Send an e-mail to mailto:acc-logging-support@cern.ch with the following pieces of information
- your NICE username
- system: WinCCOA, CMW
- NXCALS environment: PRO
- Optionally one can mention that the NXCALS database will be accessed through SWAN
Once the access is granted, please proceed with the following steps.
### 2. Accessing SWAN
The following steps should be followed in order to log-in to SWAN
1. Go to http://swan.cern.ch
2. Login with your NICE account
- SWAN is tightly integrated with CERNBox service (in fact, files created in SWAN are accessible in CERNBox). In case you have not used CERNBox, the following error message will be displayed in- dicating that your CERNBox account has not been activated yet. In order to activate your CERNBox account, please login on the website: http://cernbox.cern.ch. Afterwards, please login to SWAN service again. In case the error persists, please contact the SWAN support (cf. Chapter 3).
### 3. Selecting SWAN Environment Configuration
SWAN supports a range of software distributions. In order to execute LHC-SM quench analysis notebooks, a specific SWAN configuration has to be selected as shown below.
![SWAN Inactive CERNBox Error](figures/swan-inactive-cernbox-error.png)
A summary of recommended settings is provided in figure and table below.
## 3. 600A Circuits
The 600-A circuits come in one of two main variants:
- circuits with
- and without EE.
|Parameter|Value|
|---------|-----|
|Software stack|NXCals Python3|
|Platform|CentOS 7 (gcc8)|
|Environment script|-|
|Number of cores|4|
|Memory|10|
|Spark cluster|BE NXCALS (NXCals)|
Each variant may or may not be equipped with a DC contactor ensuring the effectiveness of the crowbar in case of a PC short circuit. Moreover, the magnets of several circuits are equipped with parallel resistors, in order to decouple the current decay in a quenching magnet from that in the rest of the circuit. Figure 1 shows a generic circuit diagram, equipped with EE and parallel resistor, as well as lead resistances and a quench resistance.
![SWAN Configure Environment](figures/swan-configure-environment.png)
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/raw/master/figures/600A/600A.png" width=75%>
After setting these parameters, please click [Start my Session] button. If you login for the first time, the project space is empty.
source: Test Procedure and Acceptance Criteria for the 600 A Circuits, MP3 Procedure, <a href="https://edms.cern.ch/document/874716/5.3">https://edms.cern.ch/document/874716/5.3</a>
![SWAN Empty Project Space](figures/swan-empty-project-space.png)
Table below provides a list of circuits to be used with these analysis notebooks
### 4. Installing Necessary Packages
SWAN provides a set of pre-installed python packages. The LHC-SM notebooks require installation of several additional packages. In order to install a package, please open a SWAN Terminal by clicking [>_] icon in the top right corner.
|RCBX family|RCD/O family|Remaining 600A circuits with EE|Remaining 600A circuits without EE|
|-----------|------------|-------------------------------|----------------------------------|
|RCBXH1|RCD|RCS|RQS (RQS.L)|
|RCBXH2|RCO|RSS|RQSX3|
|RCBXH3| |ROD|RQT12|
|RCBXV1| |ROF|RQT13|
|RCBXV2| |RQTL9|RQTL7|
|RCBXV3| |RQS (RQS.A)|RQTL8|
| | |RQTD|RQTL10|
| | |RQTF|RQTL11|
| | |RSD1|
| | |RSD2|
| | |RSF1|
| | |RSF2|
| | |RU|
![SWAN CLI Button](figures/swan-cli-button.png)
Another useful resource to find out which 600 A circuits belong to which category is the circuit tree on the MP3 website http://cern.ch/mp3
Five additional python packages have to be installed:
- tzlocal - for time zone convertion
- tqdm - for progress bar to track queries
- influxdb - for communication with an Influxdb
- plotly - for interactive plotting of circuit schematics
- lhcsmapi - for LHC-SM API
In order to install a package please execute the following command
```
$ pip install --user package_name
```
The expected output, after installing all packages, is presented in five figures below.
- SWAN Terminal output after successful installation of tzlocal package.
![SWAN pip install tzlocal](figures/swan-pip-install-tzlocal.png)
- SWAN Terminal output after successful installation of tqdm package.
![SWAN pip install tqdm](figures/swan-pip-install-tqdm.png)
- SWAN Terminal output after successful installation of influxdb package.
![SWAN pip install influxdb](figures/swan-pip-install-influxdb.png)
- SWAN Terminal output after successful installation of plotly package.
![SWAN pip install plotly](figures/swan-pip-install-plotly.png)
- SWAN Terminal output after successful installation of lhcsmapi package.
![SWAN pip install lhcsmapi](figures/swan-pip-install-lhcsmapi.png)
#### 4.1. Updating lhcsmapi Package
Please note that the first four packages (tzlocal, tqdm, influxdb, plotly) have to be installed only once while the last one is still in the development phase and subject to frequent updates. Please send us an e-mail re- quest (mailto:lhc-signal-monitoring@cern.ch) if you want to subscribe for updates. In order to update the lhcsmapi package, please execute the following command.
```
$ pip install --user --upgrade lhcsmapi
```
In case this command returns an error, please try to execute it again. Should that operation also fail, please uninstall the package by executing
```
$ pip uninstall lhcsmapi
```
and performing a fresh installation the package
```
$ pip install --user lhcsmapi
```
Should you experience any further issues with installing a package, please contact SWAN support (cf. Chapter 3).
# Notebook Upload
In order to upload an analysis notebook for the RB circuit, please follow the steps outlined below.
1. Go to LHC-SM GitLab project at https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/ tree/1.1.0/hwc/rb and select a notebook to download (for RQ, please visit: https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/tree/1.1.0/hwc/rq). You should see a notebook viewer as shown below.
![GitLab download](figures/gitlab-download.png)
2. Click the download icon as shown in Figure above.
3. Go to your SWAN space and create a new project (e.g., lhc-sm-apps) by clicking plus button indicated in Figure below.
![SWAN create new project](figures/swan-create-new-project.png)
4. Go to the new project by clicking its name.
|Type|Test|Current|Description|Notebook|Example report|
|----|----|-------|-----------|--------|--------------|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_600A\_with\_without\_EE\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/600A/AN_600A_with_without_EE_FPA.ipynb)|-|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_600A\_RCDO\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/600A/AN_600A_RCDO_FPA.ipynb)|-|
|Operation|FPA|I\_PNO|FPA during operation with magnets quenching|[AN\_600A\_RCBXHV\_FPA](https://gitlab.cern.ch/LHCData/lhc-sm-hwc/-/blob/master/600A/AN_600A_RCBXHV_FPA.ipynb)|-|
5. Create a new folder for the quench analysis notebook by clicking + button and selecting Folder; see Figure below.
# User Guide
The execution of notebooks is carried out with SWAN service (http://swan.cern.ch) and requires three steps:
1. Getting NXCALS Access (once only)
2. Logging to SWAN
3. Setting up an appropriate environment script (done at each login)
4. Running an appropriate notebook
![SWAN create new folder](figures/swan-create-new-folder.png)
## 1. NXCALS Access
The NXCALS database requires an assignment of dedicated access rights for a user.
If you want to query NXCALS with the API, please follow a procedure below on how to request the NXCALS access.
By default, a new folder is named ’Untitled Folder’. Please rename the folder to ’hwc’. To do so, select the folder and click rename button as shown in Figure below.
1. Go to http://nxcals-docs.web.cern.ch/current/user-guide/data-access/nxcals-access-request/ for most updated procedure
2. Send an e-mail to mailto:acc-logging-support@cern.ch with the following pieces of information:
- your NICE username
- system: WinCCOA, CMW
- NXCALS environment: PRO
Optionally one can mention that the NXCALS database will be accessed through SWAN.
Once the access is granted, you can use NXCALS with SWAN.
## 2. Logging to SWAN
The following steps should be followed in order to log-in to SWAN
1. Go to http://swan.cern.ch
2. Login with your NICE account
- SWAN is tightly integrated with CERNBox service (in fact, files created in SWAN are accessible in CERNBox). In case you have not used CERNBox, the following error message will be displayed in- dicating that your CERNBox account has not been activated yet. In order to activate your CERNBox account, please login on the website: http://cernbox.cern.ch. Afterwards, please login to SWAN service again. In case the error persists, please contact the SWAN support (see Section Help and Feedback at the bottom).
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/swan-inactive-cernbox-error.png" width=50%>
![SWAN rename folder](figures/swan-rename-folder.png)
## 3. Setting an Environment Script
In order to execute the HWC notebooks, one requires `lhc-sm-api` package and HWC notebooks. To this end, we created a dedicated environment script to prepare the SWAN project space.
The script sets a path to a virtual environment with the necessary packages (for more details, cf. https://lhc-sm-api.web.cern.ch/lhc-sm-api/user_install.html#preinstalled-packages) as well as makes a copy of HWC notebooks to `hwc` notebooks. **Note that in order to ensure compatibility between package and notebook versions, the `hwc` folder is deleted each time the script is executed'.**
Firstly, contact the Signal Monitoring team (mailto:lhc-signal-monitoring@cern.ch) in order to get read access to the EOS folder with pre-installed packages and HWC analysis notebooks.
6. Click ’hwc’ folder to enter it.
7. Inside the ’hwc’ folder create another one and name it ’rb’.
8. Click ’rb’ folder to enter it (for the RQ circuit, create rq folder accordingly).
9. Click upload icon in order to upload the hwc_rb_PM_RB_FPA.ipynb notebook.
Once the access is granted, at every log-in to SWAN, please provide the following environment script:
`/eos/project/l/lhcsm/public/packages_notebooks.sh`
![SWAN upload notebook](figures/swan-upload-notebook.png)
<img src="https://gitlab.cern.ch/LHCData/lhc-sm-hwc/raw/master/figures/swan_environment_script.png" width=25%>
10. First rename the notebook to PM_RB_FPA.ipynb by removing the suffix ’hwc_rb_’ and then click the [Upload] button.
Note the following settings while configuring environment:
- Software stack: `NXCals Python3`
- Platform: `CentOS 7 (gcc7)` - default
- Environment script: `/eos/project/l/lhcsm/public/packages_notebooks.sh`
- Number of cores: `4`
- Memory: `16`
- Spark cluster: `BE NXCALS (NXCals)`
![SWAN rename notebook](figures/swan-rename-notebook.png)
## 4. Running Notebook
### 4.1. Open notebook
11. Open notebook by clicking its name. The top of the notebook is presented in Figure below.
To do so simply click its name and a new page will be opened. The top of the notebook is presented in Figure below.
![SWAN RB FPA analysis intro](figures/swan-rb-fpa-analysis-intro.png)
#### 4.2 Connection to the NXCALS Cluster
### 4.2. Connect to the NXCALS Spark Cluster
Once a notebook is opened, please click a star button as shown in Figure below in order to open the Spark cluster configuration in a panel on the right side of an active notebook.
![SWAN Open Spark Cluster Configuration](figures/swan-open-spark-cluster-configuration.png)
......@@ -199,7 +157,7 @@ The last step is a confirmation of a successful connection to the cluster.
![SWAN Spark Cluster Connection](figures/swan-spark-cluster-connection.png)
#### 3. Analysis Notebook Execution
### 4.3. Analysis Notebook Execution
A notebook is composed by cells. A cell contains either a markdown text with description or python code toexecute. Cells with markdown text have white background and can contain text, tables, figures, and hyperlinks.Cells with code have gray background and are executed by clicking a run icon in the top bar highlighted in Figure below. Alternatively, one can put a cursor in a cell with code an press a keyboard shortcut Ctrl+Enter.
![SWAN Execute Cell](figures/swan-execute-cell.png)
......@@ -274,7 +232,6 @@ The notebook creates three output files in the folder //cern.ch/eos/project/l/lh
- CSV file with MP3 results table with a subset analysis results - [fgc-timestamp]-[analysis-execution-date]-[notebook-name]\_mp3\_results\_table.csv};
- CSV file with full results table - [fgc-timestamp]-[analysis-execution-date]-[notebook-name]\_results_table.csv};
# Analysis Notebook for HWC
## Analysis Workflow
......@@ -303,7 +260,6 @@ e.g.,
- HTML report file with the snapshot of the entire notebook - [test-start]-[test-end]\_report.html;
# Help and Feedback
Despite thorough testing, while using LHC-SM quench analysis notebooks two types of issues can occur, related to:
- analysis (e.g., wrong analysis results, corrupted plots, etc.);
......@@ -320,4 +276,4 @@ There are three ways to contact SWAN support for help related to the service:
All three links are also available in the footer of SWAN website as shown in Fig. 3.1.
![SWAN Help](figures/swan-help.png)
![SWAN Help](figures/swan-help.png)
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment