nqrduck/NQRduckumentation
1
0
Fork 0
mirror of https://github.com/nqrduck/NQRduckumentation.git synced 2025-01-02 21:38:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Changed tutorial format to markdown.

Browse source
This commit is contained in:
jupfi 2024-05-10 14:12:26 +02:00
parent 687082a474
commit 299a0685e0
8 changed files with 240 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
requirements.txt
View file

@ -1,5 +1,6 @@
sphinx
pydata-sphinx-theme
myst-parser
nqrduck
nqrduck-spectrometer
nqrduck-spectrometer-limenqr

7
source/conf.py
View file

@ -48,6 +48,7 @@ extensions = [
"sphinx.ext.autosummary",
"sphinx.ext.napoleon",
'sphinx.ext.todo',
'myst_parser'
]
autosummary_generate = True
@ -55,6 +56,12 @@ autodoc_default_options = {
"members": True,
}
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}
# This is required for readthedocs to work with PyQt6
autodoc_mock_imports = [
"matplotlib",

10
source/tutorials/index.rst
View file

@ -7,11 +7,13 @@ Introduction
This is a collection of different tutorials for the NQRduck program.
- :doc:`0. NQRduck Setup <tutorial_0>` - This tutorial shows you how to setup the NQRduck program.
.. toctree::
:maxdepth: 1
:caption: Tutorials
- :doc:`1. NQRduck Simulator <tutorial_1>` - This tutorial shows you how to use the NQRduck Simulator.
- :doc:`2. LimeNQR <tutorial_2>` - This tutorial shows you how to use the LimeNQR spectrometer with the NQRduck program.
tutorial_0
tutorial_1
tutorial_2
Tutorials in work
-----------------

26
source/tutorials/tutorial_0.rst → source/tutorials/tutorial_0.md
View file

@ -1,12 +1,12 @@
0. NQRduck Setup Tutorial 🦆
============================
# 0. NQRduck Setup Tutorial 🦆
## Introduction
Introduction
------------
This Tutorial gives a short overview of how to setup the NQRduck program. The NQRduck program is a collection of different modules that can be installed separately. The core program is the main entry point and provides a user interface to access the different modules.
Requirements
------------
## Requirements
- Python 3.10+
- pip
@ -14,22 +14,22 @@ Requirements
- About 600MB of free storage space
Steps (Linux)
-------------
## Steps (Linux)
1. Install the specified requirements.
2. Create a virtual environment and activate it:
.. code-block:: bash
```bash
python -m venv venv
. venv/bin/activate
```
3. You can now install the NQRduck core program:
.. code-block:: bash
```bash
pip install nqrduck
```
4. Run the program with `nqrduck`. This should open up a window with the NQRduck program.

67
source/tutorials/tutorial_1.md Normal file
View file

@ -0,0 +1,67 @@
# 1. NQRduck Simulator Tutorial 🦆
## Introduction
This Tutorial gives a short overview of how to use the NQRduck Simulator. The NQRduck Simulator is a module of the NQRduck program that allows you to simulate NQR signals and spectra.
## Requirements
* All requirements from the [NQRduck Setup Tutorial](0_NQRduck_Setup.md)
## Steps (Linux)
1. Switch to the Spectrometer module in the NQRduck program.
| ![The Spectrometer module.](Figures/1_spectrometer_tab.png) |
| :--: |
| Figure: The `Spectrometer` module. The `Settings` are on the left side and the `Pulse Programmer` on the right side.|
2. You can now see two different sections in the Spectrometer module:
- The left side are the spectrometer `Settings`. These are values that don't change during a `Pulse Sequence`.
- The right side is the `Pulse Programmer`. Here you can create sequences of pulses that are executed during the simulation.
3. Create a simple Free Induction Decay (FID) sequence in the `Pulse Programmer` on the right side:
- A sequence is made up of different `Events` that are executed subsequently. Different `Events` are rows in the `Pulse Programmer` table.
- For every `Event` you can specify a certain duration and a name.
- Every `Event` now has `Pulse Parameters` associated with it. For the Simulator, these are the TX and the RX Pulse Parameters.
| <img src="Figures/1_pulseprogrammer.png" width=50%> |
|:-------------------------------------------------------------:|
| **Figure:** An exemplary FID sequence. |
| Description |
| **a.) The different events:**<br>**Pulse:** Our TX Pulse excites the sample and is set active by adjusting the relative TX Amplitude to a value larger than 0 (usually 1.0).<br>**Blank:** Waiting time between the TX Pulse and RX Readout to await coil ringing.<br>**RX:** The ADC Readout that measures the signal. Without an RX event, the whole simulation appears in the plot.<br>**TR:** The repetition time between the different averages. Not strictly necessary for the simulation right now. |
| **b.)** The Pulse Parameters for the selected event. |
| **c.)** The Pulse Parameters for the Pulse Event. |
| **d.)** The Pulse Parameters for the RX Event. |
| **e.)** The duration of the different events. |
You can add new `Events` by clicking on the `New Event` button. `Events` can be moved by clicking the purple Arrows. You can delete an `Event` by clicking on the garbage can icon. The `Event` duration and name can be changed.
Advisable durations for the different events are:
- **Pulse:** 3µs - Relative TX Amplitude: 1.0
- **Blank:** 8µs
- **RX:** 150µs
- **TR:** 10ms (not strictly necessary for the simulation, be careful since this will also 'use up' your simulation points.)
4. You can now adjust the settings of the Simulator on the right side. Different settings are for example the number of simulation points or the noise level.
5. To start the simulation, switch back to the `Measurement` tab. Enter a `Target Frequency` of 83.56MHz and 100 `Averages`. Now press the `Start Measurement` button.
6. You should see an exponential decay in the plot. This is the FID signal that you just simulated.
- The signal might look weird if you didn't set the correct Pulse Parameters. Try to adjust either the length of your TX event or the pulse power to achieve a $\frac{\pi}{2}$ flip angle.
If your resolution looks low, try adjusting the number of simulation points in the `Settings` tab.
7. Try setting the experiment temperature to 77K and see how the signal changes.
9. Save your pulse sequence by clicking on the `Save pulse sequence` button in the Pulse Programmer.
8. Next try to implement a Spin Echo (SE) sequence. Try to center your RX event around the echo of the signal. Play around with relaxation times and see how the signal changes.
10. If you found a pulse sequence that you like, you can save it by clicking on the `Save pulse sequence` button in the Pulse Programmer.
11. We will now run these sequences on the real hardware. See [Tutorial 2](2_LimeNQR.md) for more information.
## Notes:
- With some of the last updates I broke the signal processing options. I will fix this in the next updates. For now, you can only simulate the signal and not process it.
- The `Measurement Frequency` doesn't have any effect on the simulation right now. It is only used for the real hardware.
<!-- TODO:
Screenshot of the pulse programmer with a simple FID sequence
-->

2
source/tutorials/tutorial_1.rst
View file

@ -1,2 +0,0 @@
1. NQRduck Simulator Tutorial 🦆
================================

146
source/tutorials/tutorial_2.md Normal file
View file

@ -0,0 +1,146 @@
# 2. LimeNQR Tutorial 🦆
## Introduction
The [LimeNQR](docs/LimeNQR.md) spectrometer can be used with the NQRduck program for magnetic resonance experiments.
This tutorial will show you how to use the [LimeNQR](docs/LimeNQR.md) spectrometer with the NQRduck program. We will perform a loopback measurement, a TX check, and a NQR measurement on a sample.
## Requirements
- All requirements from the [NQRduck Setup Tutorial](0_NQRduck_Setup.md)
- On Debian-based systems, the following packages are required to build the software:
```
sudo apt-get install g++ cmake liblimesuite-dev libhdf5-dev
```
On Arch Linux, the following packages are required to build the software:
```
sudo pacman -S gcc cmake limesuite hdf5
```
- Last but not least, install the [nqrduck-spectrometer-limenqr](https://github.com/nqrduck/nqrduck-spectrometer-limenqr) module:
```
pip install "nqrduck-spectrometer-limenqr @ git+https://github.com/nqrduck/nqrduck-spectrometer-limenqr"
```
### ⚠️ Safety Tips ⚠️
- Don't leave the [low noise amplifier (LNA)](docs/LNA.md) unconnected on the in- and output. This could damage the [LNA](docs/LNA.md).
- Don't output a pulse without a load connected to the TX port. This could damage the [Radio Frequency Amplifier (RFPA)](docs/RFPA.md).
- Don't pulse at any other where the probe coil is not tuned and matched. This could damage the setup.
- Don't forget the TR event in your pulse sequence. This could damage the setup.
- Make sure the [Pre Amplifier](docs/PreAmp.md) is cooled. It will burn out otherwise.
- If you get an error when running measurements with the LimeNQR spectrometer, try another USB port. USB 3.0 ports are recommended. Also try to use a port that is directly connected to the motherboard.
## Steps (Linux)
### Loopback Measurement
This is a simple test to check if the LimeNQR spectrometer is working correctly. We measure the output signal of the LimeNQR spectrometer with the receive path of the LimeNQR spectrometer.
| <img src="Figures/2_loopback_schematic.png" width=40%> |
|:--:|
| Figure: Schematic for the loopback measurement.|
1. Check that you installed the nqrduck-spectrometer-limenqr module. You can click on the `Spectrometer` button in the menu bar and select `LimeNQR`. Another way to check if the module is installed is to open `Help" -> About Modules`.
2. Connect the USB cable of the LimeNQR spectrometer to your computer.
3. Load the FID pulse sequence into the `Pulse Programmer`. You can use the same sequence as in the [NQRduck Simulator Tutorial](1_Simulator.md).
4. Adjust the RX event to occur at the same time as the TX Pulse. We will perform a "Loopback" measurement, where we observe the output signal of of the LImeNQR spectrometer.
5. Connect the TX and RX ports of the LimeNQR spectrometer with a SMA cable and a 20dB attenuator.
| <img src="Figures/2_Loopback.png" width=100%> |
|:--:|
| Figure: Picture of the Spectrometer setup for the loopback measurement. The silver part is the attenuator. The RX and TX path are connected.|
6. Go to the measurement module, enter a `Target Frequency` and a number of `Averages` (100) and click `Start Measurement`. You should be able to see the output signal of the LimeNQR spectrometer.
7. You can now change the pulse shape of the TX pulse and observe the signal change in the measurement module after running the measurement again.
8. You can also observe the signal in frequency space by clicking on the `FFT` button in the measurement module.
### TX Check
Here we will perform a test if the [RFPA](docs/RFPA.md is working correctly. We will measure the output signal of the [RFPA](docs/RFPA.md) by pulsing into a 50 Ohm dummy load and observing the signal with an oscilloscope.
| <img src="Figures/2_dummy_load.jpg" width=40%> |
|:--:|
| Figure: Picture of the dummy load.|
1. Load the FID pulse sequence in the `Pulse Programmer`. You can use the same sequence as in the [NQRduck Simulator Tutorial](1_Simulator.md). Make sure to add an TR event to the sequence. The last event in your pulse sequence will always be interpreted as the TR time. If you don't add a TR event, the duty cycle of the TX pulse might be too high and you could damage things.
2. We use a [pre-amplifier](docs/PreAmp.md) to amplify the signal of the LimeNQR spectrometer. Connect the TX port of the LimeNQR spectrometer to the Pre Amplifier. Connect the Pre Amplifier to the 12V Power Supply. Make sure the Pre Amplifier is cooled because it will burn out otherwise. The RX port of the LimeNQR spectrometer can stay unconnected. Connect the Dummy Load to the Probe Port of the [transcoupler](docs/Transcoupler.md).
3. Connect the gate of the LimeNQR to the oscilloscope on Channel 1. Trigger on a rising flank on Channel 1. Use a timescale that makes sense for your pulse sequence.
4. Go to the spectrometer `Settings` and set the `TX gain` to `10`.
5. Turn on the [RFPA](docs/RFPA.md - you should hear the cooling fan of the [RFPA](docs/RFPA.md spinning.
6. Plug in the LimeNQR spectrometer you should hear the LimeNQR fan spinning.
7. Set the `Target Frequency` to 83.56 MHz and the number of `Averages` to 100. Click `Start Measurement`. You should see the pulse on the oscilloscope. The blue trace is the Gate Signal and the yellow trace is the TX pulse.
8. Observe the pulse on Channel 2 of the oscilloscope, by connecting it to the Directional Coupler (FWD). Use AC coupling.
### NQR Measurement
We will now perform a NQR measurement on a sample. We will use the BiPh3 sample for this tutorial.
| <img src="Figures/2_BiPh3.jpg" width=25%> |
|:--:|
| Figure: Picture of the BiPh3 sample. |
1. Load the NQR pulse sequence in the `Pulse Programmer` by clicking the `Load pulse sequence`. You can use the same sequence as in the NQRduck Simulator Tutorial. Make sure not to use the Loopback measurement where the RX event occurs at the same time as the TX pulse.
2. Put the sample into the probe coil and tune and match it at 83.56 MHz using a Network Analyzer. You can find detailed instructions at [Tuning and Matching](docs/TuningAndMatching.md).
3. Connections ⚡:
The experiment now has to be set up as follows:
| <img src="Figures/2_measurement_schematic.png" width=100%> |
|:--:|
| Figure: Schematic of the NQR measurement setup. The power connections are not depicted. |
- [ ] Connect the 12V Power Supply to the LimeNQR spectrometer and the USB cable to your computer.
- [ ] Connect the Gate of the LimeNQR spectrometer to the Gate of the [RFPA](docs/RFPA.md.
- [ ] Connect the TX port of the LimeNQR spectrometer to the Pre Amplifier.
- [ ] Connect the Pre Amplifier to the 12V Power Supply. Maker sure the Pre Amplifier is cooled because it will burn out otherwise.
- [ ] Connect the RX port of the LimeNQR spectrometer to [LNA](docs/LNA.md).
- [ ] Connect the [LNA](docs/LNA.md) to the 5V Power Supply.
- [ ] Connect the probe coil to the probe port of the [transcoupler](docs/Transcoupler.md).
| <img src="Figures/2_fullmeas_pic.jpg" width=100%> |
|:--:|
| Figure: Picture of the NQR measurement setup. |
4. Go to the measurement module, enter a `Target Frequency` of 83.56 MHz and a number of `Averages` (1000) and click `Start Measurement`. You should be able to see the NQR signal of the BiPh3 sample. Don't pulse at any other frequency than 83.56 MHz, because you could damage the setup.
5. You should see a peak from your signal at the Intermediate Frequency (IF) that was set in the `Spectrometer` tab. The default value is 5MHz.
- What else do you see in the spectrum? Can you identify the different peaks?
6. To make sure that the signal is coming from the sample, you can remove the sample from the probe coil and see if the signal disappears.
⚠️CAREFUL!⚠️ You need to tune and match the probe coil again after removing the sample.
7. You can now also try a Spin Echo if the FID worked. If you have very long sequences, make sure to increase the `Acquisition Time` in the `Spectrometer` settings.
.

2
source/tutorials/tutorial_2.rst
View file

@ -1,2 +0,0 @@
2. LimeNQR Tutorial 🦆
======================