From d5bf5637ea6e60cf20be90a5bb5aef7ca6748746 Mon Sep 17 00:00:00 2001 From: Lingxin Meng Date: Thu, 19 Jun 2025 14:49:56 +0100 Subject: [PATCH] more formatting and minor update of content --- docs/index.md | 20 +++--- docs/install.md | 12 ++-- docs/workflow.md | 175 +++++++++++++++++++++++++++-------------------- 3 files changed, 118 insertions(+), 89 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5c2a64eef..3700e132b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,8 +40,10 @@ The necessary capacity would depend on the number of modules produced at the site. The `LocalDB` data can be synchronized to an independent `MongoDB` service to support backup. -!!! Note For `CentOS7` installation, `MongoDB v4.2.21` is installed by default. -We have not testest `MongoDB v5` from the developer side. +!!! note + + For `CentOS7` installation, `MongoDB v4.2.21` is installed by default. + `MongoDB` version 4--7 have been tested to work. For more info on the compatibilities see https://www.mongodb.com/docs/languages/python/pymongo-driver/v4.8/reference/compatibility/ ## QC tests and LocalDB @@ -71,9 +73,11 @@ time-series data: only a clipped _snapshot_ of such data can be associated to each electrical scan. Such clipping task is not done within the `LocalDB` server side, but it is a task to be done as a post-process of `YARR` scans. -!!! Warning The underlying data scheme between `InfluxDB 1.x` and `InfluxDB 2.x` -is different and not compatible. The current `LocalDB` system is only adapted to -`InfluxDB 1.x`. Inclusion of `InfluxDB 2.x` is a future ToDo. +!!! warning + + The underlying data scheme between `InfluxDB 1.x` and `InfluxDB 2.x` + is different and not compatible. The current `LocalDB` system is only adapted to + `InfluxDB 1.x`. Inclusion of `InfluxDB 2.x` is a future ToDo. ## Host specs @@ -89,6 +93,6 @@ is a separate host PC from those used to run scans. ## OS support -We officially support `CentOS7` and `CentOS Stream 8` Linux system in this -document as the default operating systems. One should be able to install the -service to `macOS`, but it should be the user's responsibility to setup. +We officially support `CentOS7`, `CentOS Stream 8` and `Alma 9` Linux system in +this document as the default operating systems. One should be able to install +the service to `macOS`, but it should be the user's responsibility to setup. diff --git a/docs/install.md b/docs/install.md index 4df67c686..9e12ca3f1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -51,9 +51,9 @@ The following examples are using `v2.6.1` of the `localdb` viewer. docker network create web ``` -!!! note + !!! note - Make sure the local volume exists to persist the mongoDB via `mkdir -p ./data/mongodb`. + Make sure the local volume exists to persist the mongoDB via `mkdir -p ./data/mongodb`. Then we can create the `mongodb` container and put it on this network: @@ -128,9 +128,9 @@ The following examples are using `v2.6.1` of the `localdb` viewer. === "Docker Compose" -!!! note + !!! note - Make sure the local volume exists to persist the mongoDB via `mkdir -p ./data/mongodb`. + Make sure the local volume exists to persist the mongoDB via `mkdir -p ./data/mongodb`. ```yaml title="docker-compose.yml" version: "3.8" @@ -186,9 +186,9 @@ The following examples are using `v2.6.1` of the `localdb` viewer. We demonstrate the use of a reverse-proxy to set this up. There are plenty of benefits to using a reverse proxy such as load balancing, setting up TLS (SSL certificates), and provides metrics for diagnostics and monitoring of your web traffic. In this example, [traefik](https://doc.traefik.io/traefik/) is used for the reverse-proxy. -!!! note + !!! note - Make sure the local volume exists to persist the mongoDB via `mkdir -p ./data/mongodb`. You'll additionally need to create the external network for handling incoming requests via `docker network create web`. + Make sure the local volume exists to persist the mongoDB via `mkdir -p ./data/mongodb`. You'll additionally need to create the external network for handling incoming requests via `docker network create web`. ```yaml title="docker-compose.yml" version: "3.8" diff --git a/docs/workflow.md b/docs/workflow.md index 056324b42..b6bca0822 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -2,23 +2,19 @@ ## Version information -This document is compatible with `localdb-tools` version `2.2.36` or later. +This document is compatible with `localdb-tools` version `2.2.36` or later. The +corresponding `YARR` version is `v1.5.2` or later. -- The corresponding `YARR` version is `v1.5.2` or later. -- You need to deploy the following packages in your local DAQ system: - - `module-qc-database-tools 2.4.8` or later - - `module-qc-tools 2.2.7` or later - - `module-qc-analysis-tools 2.2.9` or later +For the user-facing module QC \* tools please see their dedicated +documentations: -## tl;dr +- module QC database tools: https://atlas-itk-pixel-mqdbt.docs.cern.ch +- module QC measurement tools: https://atlas-itk-pixel-mqt.docs.cern.ch +- module QC analysis tools: https://atlas-itk-pixel-mqat.docs.cern.ch -The LBNL team provides the example -[bash script to run the all chain of the electrical test of a stage](https://gitlab.cern.ch/atlas-itk/pixel/module/module-qc-database-tools/-/snippets/2631). +One additional package is used by all mq\*t above but is not user-facing: -Some presentations are also available - -- [Emily Thompson, Upgrade Week, May 10, 2023](https://indico.cern.ch/event/1223748/contributions/5393853/attachments/2644780/4577698/UpgradeMay2023_ModuleQCv2.pdf) -- [Kehang Bai, Module Group Meeting, May 25, 2023](https://indico.cern.ch/event/1289710/contributions/5419231/attachments/2653318/4596038/QC_V2_workflow_Kehang_Bai_module_meeting.pdf) +- module QC data tools: https://atlas-itk-pixel-mqdt.docs.cern.ch ## Module Assembly @@ -41,13 +37,19 @@ You will be requested to input only the following information: ![Module Assembly Link](images/workflow/module_assemble_2.png) -!!! note All subcomponents' location on Production DB must be your site (the -site you are registered in Production DB). +!!! note + + All subcomponents' location on production DB must be your site (the + site you are registered in production DB). + +!!! note -!!! note In order to assemble the module, BareModule needs to have all FE chips -already. + In order to assemble the module, BareModule needs to have all FE chips + already. -!!! note All sub-components need to be not assembled previously. +!!! note + + Not all sub-components need to be assembled previously. Once the module is successfully assembled, the module's information is downloaded to your LocalDB, and you are ready to go. @@ -65,22 +67,26 @@ restults of previous stages. ![Module Download 2](images/workflow/module_download_2.png) -!!! note It is not only a module you can download with this interface. -Standalone sub-components of Sensor Tile, Bare Module, PCB are supported on top -of Module. +!!! tip + + This interface can be used to pull any supported components like Module, Sensor Tile, Bare Module, PCB etc. -!!! warning If your downloaded module's stage is not a valid one (e.g. -`MODULETOPCB` which was deprecated), you need to switch the module's stage to -the correct one by hand. You can do this by clicking the "Switch Stage" yellow -button of the module's page. +!!! warning -!!! note Please do not switch the stage except the above reason, unless you -understand the behavior e.g. for debugging purpose. You may end-up wiping -previous stages test records at the worst case. + If your downloaded module's stage is not a valid one (e.g. + `MODULETOPCB` which was deprecated), you need to switch the module's stage to + the correct one by hand. You can do this by clicking the "Switch Stage" yellow + button of the module's page. + +!!! warning + + Please do not switch the stage except the above reason, unless you + understand the behavior e.g. for debugging purpose. You may end-up wiping + previous stages test records at the worst case. ## Simple Electrical Tests -The following tests are the so-called simple electrical tests. +The following tests are the simple electrical tests: - ADC Calibration (ADC_CALIBRATION) - Analog Readback (ANALOG_READBACK) @@ -128,18 +134,18 @@ Running a simple electrical test is essentially just running 3 steps: Using the result of the analysis, the config file is revised **locally** within the DAQ host. -The -[bash script](https://gitlab.cern.ch/atlas-itk/pixel/module/module-qc-database-tools/-/snippets/3222) -embeds these steps and loop over Tests. +!!! note -!!! note The chip config inside LocalDB is also revised reflecting the analysis -output when `module-qc-tools-upload` is executed. + The chip config inside LocalDB is also revised reflecting the analysis + output when `module-qc-tools-upload` is executed. ## YARR Chip Scans -!!! note Before going through this section, user is expected to have a basic -idea of how the chip config is administrated in LocalDB. If you are not familiar -with, please go through [the doc](../technicalities#chip-configs). +!!! note + + Before going through this section, user is expected to have a basic + idea of how the chip config is administrated in LocalDB. If you are not familiar + with, please go through [the doc](../technicalities#chip-configs). YARR chip scans are simply possible to carry out by the `scanConsole` command. However, initially you need to generate the scan connectivity and chip config @@ -151,12 +157,14 @@ Before starting anything about YARR scan, you need to make sure the presence of the module in LocalDB, and the QC stage is exactly the one you are going to test. -!!! note Immediately after signing off from the previous stage, the LocalDB -might not be ready to host any new test. If this is the case, when you navigate -to LocalDB's module page, you will see a warning message like below. -` [ WARNING_FE_CONFIG_NOT_READY ] 20UPGR91301046: WARNING: FE Chip configs for the current stage (MODULE/INITIAL_COLD) is not ready ` -Once the preparation of the stage is done, this warning message should disappear -automatically. If this is not the case, something is wrong with LocalDB. +!!! note + + Immediately after signing off from the previous stage, the LocalDB + might not be ready to host any new test. If this is the case, when you navigate + to LocalDB's module page, you will see a warning message like below. + ` [ WARNING_FE_CONFIG_NOT_READY ] 20UPGR91301046: WARNING: FE Chip configs for the current stage (MODULE/INITIAL_COLD) is not ready ` + Once the preparation of the stage is done, this warning message should disappear + automatically. If this is not the case, something is wrong with LocalDB. ### Initial Generation of configs @@ -172,7 +180,7 @@ generateYARRConfig --sn 20UPGR91301046 \ ### Running scans -Running scans is pretty standard as usual `scanConsole`: +YARR scans are run via `scanConsole`: ```bash cd path/to/yarr @@ -200,8 +208,9 @@ specifying multiple tags is as follows: -W "['my temporary test', 'DEBUG', 'MHT']" ``` -!!! warning Please avoid to use single or double quotations as a part of the tag -name. +!!! warning + + Do not use single or double quotations as a part of the tag name. With `-W` option, not only the scan outputs like occupancy map, the chip config is also uploaded to LocalDB @@ -224,11 +233,11 @@ By clicking "View" button, you can see the detail of the scan, including plots: ### Required scans -!!! note The example -[bash script](https://gitlab.cern.ch/atlas-itk/pixel/module/module-qc-database-tools/-/snippets/2631) -is provided by the LBNL group. The most accurate and up-to-date specification of -electrical tests is documented in -[this repository](https://gitlab.cern.ch/atlas-itk/pixel/module/itkpix-electrical-qc). +!!! note + + The most accurate and up-to-date specification of electrical tests is documented + in + [this repository](https://gitlab.cern.ch/atlas-itk/pixel/module/itkpix-electrical-qc). - Minimal Health Test - `std_digitalscan` @@ -271,21 +280,29 @@ evaluate the Test. The tag you specified during the YARR scan, like `MHT`, `TUN`, or timestamp or run number will hint you which scan you will need to register here. -!!! note But these are only guides up to the end, the user needs to take the -responsibility of the validity of the scan results. +!!! note + + But these are only guides up to the end, the user needs to take the + responsibility of the validity of the scan results. + +!!! tip + + Do not worry if you miss to register wrong scans, you can create more + than one complex analysis result until you meet the correct registration. + +!!! note -!!! note Do not worry if you miss to register wrong scans, you can create more -than one complex analysis result until you meet the correct registration. + You can skip to register some scans if you do not have or you could not + take those scans. The analysis can run without these scans entry. Of course, the + result of the analysis is most likely failure. -!!! note You can skip to register some scans if you do not have or you could not -take those scans. The analysis can run without these scans entry. Of course, the -result of the analysis is most likely failure. +!!! note -!!! note Although you register scans chip-by-chip, you can specify the same set -of scan runs for all chips as common. In order to do this, you just need to -check the checkbox at the bottom of the page. This checkbox is actually toggled -on by default. However, if you have reasons to select runs for individual chips, -you can do. + Although you register scans chip-by-chip, you can specify the same set + of scan runs for all chips as common. In order to do this, you just need to + check the checkbox at the bottom of the page. This checkbox is actually toggled + on by default. However, if you have reasons to select runs for individual chips, + you can do. At the end of registration, the analysis script runs on the server side, and the QC pass/fail is judged for the test. @@ -299,30 +316,38 @@ is similar to the above Complex Electrical Tests case, but you are guided to register the record of Minimal Health Test or Tuning instead of registering YARR scans. -!!! note Do not confuse Module-level tests with FE-level tests. Electrical -Summary Test is a Module-level test, while Minimal Health Test, Tuning, etc. are -FE-level tests. +!!! note + + Do not confuse Module-level tests with FE-level tests. Electrical + Summary Test is a Module-level test, while Minimal Health Test, Tuning, etc. are + FE-level tests. ## Stage Sign-off Once all tests of the stage are filled, you can proceed signing-off the stage. -!!! note Actually you can sign-off without missing some tests, as this is a -commissioning phase and not all tests are ready to serve. +!!! info + + Stages can even be signed-off with some missing tests, as this is a + commissioning phase and not all tests are ready to serve. -You click the blue "Stage Sign-off" button under the module's page. In the next +Click the blue "Stage Sign-off" button under the module's page. In the next page, you are required to select one result per tests (there can be multiple candidate results if you have done multiple times). -!!! note Do not confuse Module-level tests with FE-level tests. Module-level -tests include E-Summary and various non-electrical tests. +!!! note + + Do not confuse Module-level tests with FE-level tests. Module-level + tests include E-Summary and various non-electrical tests. Once you selected all results, you can proceed to do sign-off. -!!! note Sign-off has technically two steps. The first step is **Local -Sign-off** where the stage is only incremented locally within the LocalDB. The -second step is **Push to Production DB** and the results are synchronized to -Production DB after this second step. +!!! info + + Sign-off has technically two steps. The first step is **Local + Sign-off** where the stage is only incremented locally within the LocalDB. The + second step is **Push to Production DB** and the results are synchronized to + Production DB after this second step. ## Non-electrical Tests -- GitLab