### Installing Backends with Pip Extras

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Optional timesolver backend dependencies can be installed automatically via the optional extras specification when using the pip command.

```Shell
pip install rydiqule[backends]
```

--------------------------------

### Confirming Rydiqule Installation

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Imports the rydiqule package in a Python interactive session and calls the `about()` function to display version and dependency information, verifying a successful installation.

```shell
>>> import rydiqule as rq
>>> rq.about()
```

--------------------------------

### Editable Installation via Pip (Standalone)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Installs the rydiqule package in editable mode directly using pip from the root of the cloned repository. Requires git for dynamic versioning.

```shell
pip install -e .
```

--------------------------------

### Upgrading Editable Installation via Pip

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Upgrades the dependencies for an editable installation of rydiqule using pip. The `-U` flag ensures dependencies are updated.

```shell
pip install -U -e .
```

--------------------------------

### Displaying Rydiqule Version Information in Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Calls the rq.about() function to print information about the installed rydiqule library, including its version and potentially details about its dependencies and build environment.

```python
rq.about()
```

--------------------------------

### Greedy Upgrade via Pip (Including Dependencies)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Upgrades the rydiqule package and all its dependencies to their latest compatible versions using pip.

```shell
pip install -U rydiqule
```

--------------------------------

### Installing Rydiqule via Pip

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Installs the rydiqule package and its dependencies using pip. This is the standard method for non-conda installations.

```shell
pip install rydiqule
```

--------------------------------

### Standard Upgrade via Pip

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Upgrades the rydiqule package to the latest version using pip. This command is the same as the initial install command but performs an upgrade if the package is already present.

```shell
pip install rydiqule
```

--------------------------------

### Editable Installation via Conda (Pip Install Step)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Installs the rydiqule package in editable mode from the current directory (assumed to be the root of the cloned repository) after uninstalling the conda version. Requires git for dynamic versioning.

```shell
(rydiqule) ~/> pip install -e .
```

--------------------------------

### Installing Rydiqule via Conda Channel

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Installs the rydiqule package and its dependencies from the specified rydiqule anaconda channel into the currently active conda environment.

```shell
(rydiqule) ~/> conda install -c rydiqule rydiqule
```

--------------------------------

### Installing CyRK with Conda

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

For conda installations, the CyRK dependency must be installed manually using the specified channel.

```Shell
conda install -c rydiqule CyRK
```

--------------------------------

### Initializing Rydiqule Sensor (F1-F0) (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Creates a new instance of the rydiqule.Sensor class, initialized with the ground (g) and excited (e) state manifolds defined for the F=1 to F'=0 transition. This sensor will be used for the second experiment setup.

```python
s = rq.Sensor([g,e])
```

--------------------------------

### Initializing Rydiqule Sensor with States

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Creates an instance of the Rydiqule Sensor class, which will manage the atomic system, by providing the previously defined ground and excited states.

```python
s = rq.Sensor([g,e])
```

--------------------------------

### Editable Installation via Conda (Uninstall Step)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Removes the conda-installed version of rydiqule from the environment to prepare for an editable installation from a local source repository using pip.

```shell
(rydiqule) ~/> conda remove rydiqule --force
```

--------------------------------

### Setup Autoreload in IPython/Jupyter

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Level_Diagram.ipynb

Loads the autoreload extension and sets it to reload all modules automatically before executing code. Useful for interactive development.

```python
%load_ext autoreload
%autoreload 2
```

--------------------------------

### Scanning RF Amplitude and Calculating Responsivity (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Iterates through a list of RF amplitudes to test the sensor's response. For each amplitude, it defines the time-dependent RF coupling, updates the RF transition coupling in the sensor model, solves the time evolution starting from a steady-state initial condition, and calculates the peak-to-peak signal from the density matrix, storing the result.

```python
pk_to_pk_result = np.zeros(num_Amps)

for idx, amp in enumerate(amp_list):
    #define and solve for rf input
    
    rf = sig_and_LO(2*np.pi*rf_freq, 5, amp)
    rf_transition = {'states':(2,3), 'rabi_frequency':rf_rabi, 'detuning':1, 'time_dependence': sig_LO_RWA(1, amp)}
    RbSensor_time.add_couplings(rf_transition)
    time_sol = rq.solve_time(RbSensor_time, end_time, sample_num,  init_cond=sol_init.rho, atol=1e-7, rtol=1e-7)
    
    #calculate responsivity
    pk_to_pk_signal = np.ptp(time_sol.rho[100:,3])
    pk_to_pk_result[idx] = pk_to_pk_signal
```

--------------------------------

### Creating Conda Environment for Rydiqule

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Creates a new conda virtual environment named 'rydiqule' with a specific Python version (3.11) and activates it. This isolates the installation from other Python projects.

```shell
(base) ~/> conda create -n rydiqule python=3.11
(base) ~/> conda activate rydiqule
```

--------------------------------

### Getting Library Information with rq.about() (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/Saturated_Absorption_Spectroscopy.ipynb

Calls the `about()` function from the `rq` library to display information about the library, such as version or configuration details.

```python
rq.about()
```

--------------------------------

### Initializing Rydiqule Sensor in Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Initializes a rydiqule.Sensor object with the combined lists of ground and excited states. It then prints the total list of states and the count of states included in the sensor.

```python
s = rq.Sensor(g_list+e_list)
print(s.states)
print(f'There are {len(s.states):d} total states')
```

--------------------------------

### Upgrading Rydiqule via Conda

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/installation.rst

Upgrades the rydiqule package to the latest version available in the configured conda channels within the active environment.

```shell
conda upgrade rydiqule
```

--------------------------------

### Print Current Datetime (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Imports the datetime module, gets the current time, and prints it to the console. Useful for timestamping notebook execution.

```python
import datetime

##***LAST UPDATE***##
now = datetime.datetime.now()
print(now)
```

--------------------------------

### Building PDF Documentation with Sphinx Shell

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/dev/docs.rst

Command to build the PDF version of the documentation using Sphinx. This process requires `perl`, a functional LaTeX installation including the `latexmk` package, and the GNU FreeFont collection. The resulting PDF file, named `rydiqule.pdf`, will be found in the `docs/build/latex/` subdirectory.

```shell
make latexpdf
```

--------------------------------

### Importing datetime and numba

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_Heterodyne_Doppler.ipynb

Imports the `datetime` module to get the current time and `numba` for potential performance optimizations. It then prints the current timestamp.

```python
import datetime
from numba import vectorize, float64
##***LAST UPDATE***##
now = datetime.datetime.now()
print(now)
```

--------------------------------

### Import Rydiqule and Dependencies

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Level_Diagram.ipynb

Imports necessary libraries: matplotlib for plotting, numpy for numerical operations, rydiqule for atomic system simulation, and arc for atomic data.

```python
import matplotlib.pyplot as plt
import numpy as np
import rydiqule as rq
from arc import *
```

--------------------------------

### Displaying Rydiqule Version

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Time_solve_benchmarks.ipynb

Prints information about the installed Rydiqule version and its dependencies.

```python
rq.about()
```

--------------------------------

### Initializing rydiqule Sensor with Integer Basis Size (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Demonstrates the simplest way to create a rydiqule Sensor object by providing an integer representing the number of states in the basis. The states will be implicitly labeled by integers starting from 0.

```python
basis_size = 3
simple_sensor = rq.Sensor(basis_size)
```

--------------------------------

### Setup Cold Atom 3-Photon System (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/3-photon_example.ipynb

Defines parameters for a 4-level cold atom system, including detunings, Rabi frequencies for probe, dressing, and coupling lasers, basis size, and the gamma matrix for spontaneous decay rates. Initializes a rydiqule Sensor object.

```python
detunings = np.linspace(-20,20,41)

probe = {'states':(0,1), 'rabi_frequency':2*np.pi*0.1,'detuning':2*np.pi*0}
dress = {'states':(1,2), 'rabi_frequency':2*np.pi*2}
couple = {'states':(2,3), 'rabi_frequency':2*np.pi*2, 'detuning':2*np.pi*detunings}

basis_size = 4
gam = np.zeros((basis_size,basis_size),dtype=np.float64)
gam[1,0] = 6
gam[2,1] = 0.66
gam[3,2] = 10e-3
gamma_matrix = 2*np.pi*gam

sensor = rq.Sensor(basis_size)
sensor.add_couplings(probe,couple)
sensor.set_gamma_matrix(gamma_matrix)
```

--------------------------------

### Importing core libraries

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_Heterodyne_Doppler.ipynb

Imports essential libraries for numerical computation (`numpy`), the main simulation library (`rydiqule`), and plotting (`matplotlib.pyplot`). These are standard imports for scientific Python notebooks.

```python
import numpy as np
import rydiqule as rq
import matplotlib.pyplot as plt
```

--------------------------------

### Running Full Rydiqule Test Suite (Shell)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/dev/tests.rst

Executes the complete Rydiqule test suite, including tests in the `tests/` subdirectory and docstring examples, using the pytest command from the project base directory.

```shell
pytest
```

--------------------------------

### Import Core Libraries (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Imports standard Python libraries numpy and matplotlib.pyplot, along with the rydiqule library, aliasing them for convenience. These are essential for the rest of the notebook's functionality.

```python
import numpy as np
import rydiqule as rq
import matplotlib.pyplot as plt
```

--------------------------------

### Solving Time Domain System with rydiqule Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Solves the system in the time domain using the `rq.solve_time` function. It specifies the simulation end time, the number of sample points, and sets absolute and relative tolerances for the solver.

```python
%%time
end_time = 10 #microseconds
sample_num = 10

time_solution = rq.solve_time(RbSensor_time, end_time, sample_num, atol=1e-6, rtol=1e-6)
```

--------------------------------

### Configure Autoreload Extension (IPython)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Loads the IPython autoreload extension and sets it to mode 2, which automatically reloads all modules (except those excluded by %aimport) before executing the next line. This helps in interactive development by reflecting code changes without manual reloading.

```python
%load_ext autoreload
%autoreload 2
```

--------------------------------

### Enabling autoreload (IPython)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_Heterodyne_Doppler.ipynb

These are IPython magic commands used in interactive environments like Jupyter notebooks. `%load_ext autoreload` loads the extension, and `%autoreload 2` configures it to automatically reload all modules before executing code, which is useful during development.

```python
%load_ext autoreload
%autoreload 2
```

--------------------------------

### Solving Time Domain with Custom Initial Condition in rydiqule Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Calculates a steady-state solution for a sensor configuration to use as an initial condition for a subsequent time-domain solve. It then performs the time-domain simulation using `rq.solve_time`, providing the calculated steady-state density matrix.

```python
RbSensor_ss.add_couplings(blue_laser)
sol_init = rq.solve_steady_state(RbSensor_ss)

sample_num=250
end_time = 10

time_sol_beat = rq.solve_time(RbSensor_time, end_time, sample_num,  init_cond=sol_init.rho)

print(time_sol_beat.rho.shape)
```

--------------------------------

### Initialize Rydiqule Sensor and Add Couplings

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Level_Diagram.ipynb

Initializes a rydiqule Sensor object with a basis size of 4 and adds three sequential laser couplings between states (0,1), (1,2), and (2,3) with specified rabi frequencies, detunings, and phases.

```python
test_ss = rq.Sensor(basis_size=4)
test_ss.add_couplings({'states': (0,1), 'rabi_frequency': 5.0, 'detuning': 1.0, 'phase': 0.1})
test_ss.add_couplings({'states': (1,2), 'rabi_frequency': 10.0, 'detuning': 1.0, 'phase': 0.1})
test_ss.add_couplings({'states': (2,3), 'rabi_frequency': 15.0, 'detuning': 1.0, 'phase': 0.1})
```

--------------------------------

### Solving for Steady-State Density Matrix

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Computes the steady-state solution of the density matrix for the atomic system under the influence of the defined couplings, decoherence, broadening, and energy shifts.

```python
solF1F0sigNMOR = rq.solve_steady_state(s)
```

--------------------------------

### Initializing Rydiqule Sensor (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Creates an instance of the rydiqule.Sensor class, which represents the atomic system. It is initialized with the previously defined ground (g) and excited (e) state manifolds. This object will be used to add couplings, decoherence, and solve the system.

```python
s = rq.Sensor([g,e])
```

--------------------------------

### Getting Sensor Hamiltonian - Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Retrieves and prints the Hamiltonian matrix generated by the `Sensor` object. This demonstrates the effect of the added couplings, energy shifts, and coupling coefficients on the system's Hamiltonian.

```python
print(sensor_man.get_hamiltonian())
```

--------------------------------

### Setting Parameters for RF Signal and LO in Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Defines the numerical values for the local oscillator frequency (`omega_0`), the frequency difference between the signal and LO (`delta`), and the relative amplitude of the signal (`beta`).

```python
omega_0 = 2*np.pi*rf_freq
delta = 5
beta = 0.05
```

--------------------------------

### Initialize Rydiqule Sensor with Couplings and Dephasing Including Ground State

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Level_Diagram.ipynb

Initializes a rydiqule Sensor, adds couplings, creates a custom gamma matrix for dephasing including transitions to the ground state (column 0), and sets this matrix on the sensor object.

```python
test_ss = rq.Sensor(basis_size=4)
test_ss.add_couplings({'states': (0,1), 'rabi_frequency': 5.0, 'detuning': 1.0, 'phase': 0.1})
test_ss.add_couplings({'states': (1,2), 'rabi_frequency': 10.0, 'detuning': 1.0, 'phase': 0.1})
test_ss.add_couplings({'states': (2,3), 'rabi_frequency': 15.0, 'detuning': 1.0, 'phase': 0.1})

gam = np.zeros((4,4))
gam[1,0] = 5.75
gam[2,1] = 3
gam[3,2] = 10e-3
gam[:,0] += 50e-3
test_ss.set_gamma_matrix(2*np.pi*gam)
```

--------------------------------

### Accessing Sensor Coupling Edge in rydiqule Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Accesses and displays the coupling information for the specific transition between states 2 and 3 within the `RbSensor_time` object, which represents the RF transition.

```python
RbSensor_time.couplings.edges[2,3]
```

--------------------------------

### Solving Time Evolution of Sensor Model (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Executes the time integration for a Rydiqule sensor model (`RbSensor_time`) using the `rq.solve_time` function. Specifies the total simulation duration (`end_time`) and the number of time points to sample (`sample_num`).

```python
sample_num=250
end_time = 10
time_sol_beat = rq.solve_time(RbSensor_time, end_time, sample_num)
```

--------------------------------

### Building HTML Documentation with Sphinx Shell

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/dev/docs.rst

Command to build the HTML version of the documentation using Sphinx. This command should be executed from the `docs/` subdirectory of the repository. The generated HTML files will be located in the `docs/build/html/` subdirectory, with `index.html` as the main entry point.

```shell
make html
```

--------------------------------

### Calculating Susceptibility and Peak-to-Peak Result (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Processes the results from a time evolution solution (`time_sol`). Extracts a specific slice of the density matrix, representing susceptibility, and calculates the peak-to-peak value of this susceptibility over time using NumPy.

```python
susceptibility = time_sol.rho[:,100:,3]
print(susceptibility.shape)
ptp_result = np.ptp(susceptibility, axis=-1)
```

--------------------------------

### Setting Parameters for RF Amplitude Scan (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Defines the parameters required for scanning the RF amplitude to test the sensor's linear dynamic range. This includes the number of amplitude points, generating a list of amplitudes on a logarithmic scale, and setting the simulation duration and sample points.

```python
num_Amps = 50
amp_list = np.logspace(-6,0.2,num_Amps)
sample_num = 300
end_time = 3
```

--------------------------------

### Defining Atomic System and Couplings in Rydiqule

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

This snippet initializes a `rydiqule.Sensor` object with a specified basis size, defines laser couplings between states with detuning and Rabi frequency, and sets the decay matrix (`gamma`) for the system. It demonstrates the initial setup required before solving the system dynamics. Requires `rydiqule` and `numpy`.

```python
basis_size = 3
sensor_demo = rq.Sensor(basis_size)

laser_01 = {"states": (0,1), "detuning": 1, "rabi_frequency": 3}
laser_12 = {"states": (1,2), "detuning": 2, "rabi_frequency": 5}
sensor_demo.add_couplings(laser_01, laser_12)

gamma = np.zeros((basis_size, basis_size))
gamma[1:,0] = 0.1
print(gamma)
sensor_demo.set_gamma_matrix(gamma)
```

--------------------------------

### Display Rydiqule Version Info (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/Analytical 1D Doppler Demo.ipynb

Calls the rydiqule.about() function to print information about the installed rydiqule library, including its version and potentially other relevant details.

```python
rq.about()
```

--------------------------------

### Defining Vee System with rydiqule Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Defines a 3-state Vee system using string labels for states. Creates coupling dictionaries with state tuples, detuning, Rabi frequency, and a custom label. Initializes the `Sensor` by passing the basis and couplings to the constructor and then prints the coupling labels and the generated Hamiltonian.

```python
basis = ["g", "e1", "e2"]
laser_01 = {"states": ("g","e1"), "detuning": 1, "rabi_frequency": 3, "label":"red"}
laser_02 = {"states": ("g","e2"), "detuning": 2, "rabi_frequency": 5, "label":"blue"}
sensor_v = rq.Sensor(basis, laser_01, laser_02)
print(sensor_v.couplings.edges(data="label"))
print(sensor_v.get_hamiltonian())
```

--------------------------------

### Building EPUB Documentation with Sphinx Shell

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/dev/docs.rst

Command to build the documentation in the EPUB format using Sphinx. This generates an e-book version of the documentation. The output files are typically located within the `docs/build/` directory structure, similar to other build formats.

```shell
make epub
```

--------------------------------

### Printing Sensor Summary in rydiqule Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Demonstrates using the standard Python `print()` function to display a concise summary of the `rydiqule.Sensor` object, providing an overview of its configuration.

```python
print(ladder_sensor)
```

--------------------------------

### Initialize Rydiqule Sensor with Couplings and Specific Dephasing

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Level_Diagram.ipynb

Initializes a rydiqule Sensor, adds couplings, creates a custom gamma matrix for dephasing between specific states (1->0, 2->1, 3->2), and sets this matrix on the sensor object.

```python
test_ss = rq.Sensor(basis_size=4)
test_ss.add_couplings({'states': (0,1), 'rabi_frequency': 5.0, 'detuning': 1.0, 'phase': 0.1})
test_ss.add_couplings({'states': (1,2), 'rabi_frequency': 10.0, 'detuning': 1.0, 'phase': 0.1})
test_ss.add_couplings({'states': (2,3), 'rabi_frequency': 15.0, 'detuning': 1.0, 'phase': 0.1})

gam = np.zeros((4,4))
gam[1,0] = 5.75
gam[2,1] = 3
gam[3,2] = 10e-3
#gam[:,0] += 50e-3
test_ss.set_gamma_matrix(2*np.pi*gam)
```

--------------------------------

### Plotting Transmission Coefficient Over Time (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Extracts the transmission coefficient from a time-dependent solution obtained from `rq.solve_time` and plots it against time using Matplotlib. This visualizes the system's temporal response, including transient behavior and steady-state oscillations.

```python
fig, ax = plt.subplots()
transmission = time_sol_beat.rho[:,3]
ax.plot(time_sol_beat.t, time_sol_beat.get_transmission_coef())
ax.set_xlabel("time (us)");
ax.set_ylabel('transmission');
```

--------------------------------

### Solving Steady State with Rydiqule in Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Uses the rydiqule.solve_steady_state function to calculate the steady-state density matrix for the configured Sensor object 's'. The '%%time' magic command (common in Jupyter/IPython) measures the execution time of this operation.

```python
%%time
solRb87D2 = rq.solve_steady_state(s)
```

--------------------------------

### Extracting Phase Shift Observable (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Calculates an observable from the steady-state solution (solF0F1pi) that corresponds to the phase shift experienced by the probe light. This is done by specifying the coupling transition ((g, ('e', 'all'))) for which the observable is desired.

```python
susc = solF0F1pi.coupling_coefficient_observable((g, ('e', 'all')))
```

--------------------------------

### Setting up Rydiqule Sensor and Solving Time Evolution (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Demonstrates setting up a `rydiqule.Sensor` with time-dependent coupling and solving the time evolution using `rq.solve_time`. It defines a modulated field function and adds couplings, broadening, and decoherence to the sensor object before solving.

```python
#101 Mrad/s field, modulated
def my_field_norwa(t):
    return np.cos(101*t)*np.sin(10*t)

sensor_time_norwa = rq.Sensor(4)
sensor_time_norwa.add_coupling((0,1), detuning=0, rabi_frequency=1)
sensor_time_norwa.add_coupling((1,2), detuning=0, rabi_frequency=2)
sensor_time_norwa.add_coupling((2,3), transition_frequency=100, rabi_frequency=1, time_dependence=my_field_norwa)

sensor_time_norwa.add_transit_broadening(10)
sensor_time_norwa.add_decoherence((2,1), 1)
sensor_time_norwa.add_decoherence((3,2), 0.1)

#1000 samples over 3 microsecond
end_time = 3
num_pts = 1000

sol_norwa = rq.solve_time(sensor_time_norwa, end_time, num_pts)
```

--------------------------------

### Compiling LaTeX Source to PDF with latexmk Shell

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/dev/docs.rst

The second command in the two-step PDF build process. After generating LaTeX source with `make latex`, navigate to the `docs/build/latex/` directory and run this command. It uses `latexmk` with specific options to compile the LaTeX source into the final `rydiqule.pdf`, ensuring the build continues even if errors are encountered.

```shell
latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=rydiqule -interaction=nonstopmode
```

--------------------------------

### Solve Steady State and Print Density Matrix Shape (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Solves the steady-state density matrix for the RbSensor_ss object using rq.solve_steady_state. It then prints the shape of the resulting density matrix (rho), which represents the steady-state populations and coherences.

```python
ss_solution = rq.solve_steady_state(RbSensor_ss)
print(ss_solution.rho.shape)
```

--------------------------------

### Adding Sigma-Polarized Probe Coupling (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Sets up parameters for the probe light, including detuning range, Rabi frequency, and coupling coefficients (cg) specific to sigma-plus/minus polarization (coupling to mF=-1 and mF=1 ground states). It then adds this coupling to the new rydiqule.Sensor object s.

```python
dets = np.linspace(-10,10,21)
rabi_freq = 1
cg = {((1,-1), e):1,
      ((1,0), e):0,
      ((1,1), e):-1}

s.add_coupling((g,e), rabi_frequency=2*np.pi*rabi_freq, detuning=2*np.pi*dets, coupling_coefficients=cg, label='probe')
```

--------------------------------

### Initializing rydiqule Sensor with State Specifications (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Demonstrates using state specifications, where a tuple element is a list, allowing rydiqule to automatically expand it into multiple states. This is useful for concisely defining groups of states, such as those with varying quantum numbers.

```python
g = (0,0)
e = (1, [-1,0,1])
state_spec_sensor = rq.Sensor([g,e])
print(state_spec_sensor.states)
```

--------------------------------

### Getting State Populations

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Extracts the populations of each atomic sublevel from the steady-state density matrix, providing insight into how the magnetic field affects the distribution of atoms among the states.

```python
pops = rq.get_rho_populations(solF1F0sigNMOR)
```

--------------------------------

### Load Line Profiler Extension

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/Saturated_Absorption_Spectroscopy.ipynb

Loads the IPython line_profiler extension for profiling code execution line by line.

```python
%load_ext line_profiler
```

--------------------------------

### Getting Transmission Coefficient Shape from rydiqule Time Solution Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Retrieves the transmission coefficient data from the time domain solution object and prints its shape, indicating the dimensions of the output array (e.g., number of detunings x number of time points).

```python
time_solution.get_transmission_coef().shape
```

--------------------------------

### Setting Blue Laser Detuning for Dynamic Range Test (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_heterodyne_example.ipynb

Configures the blue laser coupling parameters, specifically setting the detuning to a fixed value (-8 MRad/s) determined from previous optimization. Adds this updated coupling to the sensor model, replacing any prior blue laser settings.

```python
blue_laser = {'states':(1,2), 'rabi_frequency':6.0, 'detuning': -8}
RbSensor_time.add_couplings(blue_laser)
```

--------------------------------

### Normalize Beat Signal Trace (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_Heterodyne_Doppler.ipynb

This Python function normalizes a given trace by calculating the mean of the data points starting from index 100 (to ignore the initial transient), subtracting this mean from the trace, and then dividing by the mean. An optional expansion factor can be applied.

```python
def normalize_trace(trace,expand=1):
    ave = trace[100:].mean()
    return (trace - ave)/ave*expand
```

--------------------------------

### Initializing rydiqule Sensor with String or Tuple State Labels (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Shows how to initialize a rydiqule Sensor by providing a list of explicit state labels. Labels can be strings or tuples, offering more descriptive ways to represent quantum states compared to simple integers.

```python
string_sensor = rq.Sensor(['g', 'e1', 'e2'])
tuple_sensor = rq.Sensor([(0,0), (1,-1), (1,0), (1,1)])
```

--------------------------------

### Add Coupling with Sublevel Coefficients in rydiqule Sensor

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/writeups/sublevels.rst

Extends the previous example by defining specific coupling coefficients for each sublevel within the excited state manifold. It uses `rq.expand_statespec` to get individual sublevel states and then provides a dictionary mapping state pairs to scaling factors for the Rabi frequency.

```python
g = (0, 0)
e = (1, [-1, 0, 1])
(e1, e2, e3) = rq.expand_statespec(e)

cc = {
          (g,e1): 1/sqrt(2),
          (g,e2): 0,
          (g,e3): -1/sqrt(2)
    }

s = rq.Sensor([g, e])
s.add_coupling((g, e), detuning=1, rabi_frequency=2, coupling_coefficients=cc, label='probe')
```

--------------------------------

### Configuring Rydiqule Sensor for Multi-Parameter Scan (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Initializes a Rydiqule Sensor with a 4-level basis. Defines probe, coupling, and RF transitions with specified states, detunings, and Rabi frequencies. Adds decoherence rates, including a list of values for the (1,0) transition to enable scanning this parameter. Prints the sensor configuration.

```python
basis_size = 4
sensor_sweep_2 = rq.Sensor(basis_size)

detunings = 2*np.pi*np.linspace(-10, 10, 201) #201 values between -10 and 10 MHz
probe = {"states":(0,1), "detuning": detunings, "rabi_frequency": 3, "label":"probe"}
coupling = {"states":(1,2), "detuning": 0, "rabi_frequency": 5, "label": "coupling"}
rf = {"states":(2,3), "detuning": 0, "rabi_frequency":7, "label": "rf"}

sensor_sweep_2.add_couplings(probe, coupling, rf)

gamma10 = np.linspace(0.1, 1.0, 10)
sensor_sweep_2.add_decoherence((1,0), gamma10)
sensor_sweep_2.add_decoherence((2,1), 0.1)
sensor_sweep_2.add_decoherence((3,0), 0.1)

print(sensor_sweep_2)
```

--------------------------------

### Defining Atomic States for F1-F0 Transition (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Defines the ground state 'g' as a manifold with three states (1, [-1, 0, 1]) and the excited state 'e' as a single state (0, 0). This reverses the degeneracy compared to the previous example, representing a different hyperfine transition.

```python
g = (1, [-1,0,1])
e = (0, 0)
```

--------------------------------

### Adding Optical Coupling to Rydiqule Sensor in Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Defines a range of probe detunings using numpy.linspace and a Rabi frequency. It then adds an optical coupling (labeled 'probe') to the Sensor object 's', specifying the coupled states, Rabi frequency, detuning range, and the pre-calculated coupling coefficients.

```python
dets = np.linspace(-310, 205, 231)
rabi_freq = 1

s.add_coupling((g_spec, e_spec), rabi_frequency=2*np.pi*rabi_freq, detuning=2*np.pi*dets, coupling_coefficients=cg, label='probe')
```

--------------------------------

### Setting Custom Initial Condition and Plotting Rydiqule Solution (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Illustrates how to manually set the initial condition for `rq.solve_time` by providing an array of zeros representing all population in the ground state. It then calculates and plots the imaginary part of the coupling coefficient observable for this new solution.

```python
all_ground = np.zeros(4**2-1)
sol_norwa_ground = rq.solve_time(sensor_time_norwa, end_time, num_pts, init_cond=all_ground)
susc_norwa_ground = sol_norwa_ground.coupling_coefficient_observable()

fig, ax = plt.subplots()
ax.plot(sol_norwa_ground.t, susc_norwa_ground.imag)
plt.show()
```

--------------------------------

### Configuring sensor cell and fields

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_Heterodyne_Doppler.ipynb

Sets the RF Rabi frequency. Defines parameters for the red and blue lasers and the RF LO field as dictionaries. Initializes two `rydiqule.Cell` objects for Rb85 with the defined states and transit relaxation rate, one for steady-state and one for time-domain simulations.

```python
rf_rabi = 100 #Mrad/s
red_laser = {'states':(g,e), 'rabi_frequency':2*np.pi*5}  #fields are stored as dictioniaries
blue_laser = {'states':(e,r1), 'rabi_frequency':2*np.pi*7, 'detuning': 0}
LO_ss = {'states':(r1,r2), 'rabi_frequency':rf_rabi, 'detuning':0}


RbSensor_ss = rq.Cell(atom, [g, e, r1, r2],
                      gamma_transit=2*np.pi*1, cell_length = 0.01)
RbSensor_time = rq.Cell(atom, [g, e, r1, r2],
                      gamma_transit=2*np.pi*1, cell_length = 0.01)
```

--------------------------------

### Get Doppler Classes - Rydiqule/Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Solve_memory_footprint_calcs.ipynb

Calls the `rq.doppler_classes` function to obtain parameters or structures related to Doppler averaging classes.

```python
dop_classes = rq.doppler_classes()
```

--------------------------------

### Draw Level Diagram (Cell)

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Level_Diagram.ipynb

Generates a level diagram visualization for the previously initialized rydiqule Cell object, excluding dephasing effects.

```python
level_diagram = rq.draw_diagram(RbSensor_ss,include_dephasing=False)
```

--------------------------------

### Calculating Observable Matrices from Solution

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Extracts the matrix representation of observables, specifically the coupling coefficients between ground and excited states, from the calculated steady-state density matrix.

```python
aligned_obs = solF1F0sigNMOR.coupling_coefficient_matrix(((1, 'all'), e))
print(aligned_obs)
perp_obs = np.abs(aligned_obs)
print(perp_obs)
```

--------------------------------

### Solving Steady State in Rydiqule Cell (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Cell_Basics.ipynb

Illustrates how to solve a system defined in a `rydiqule.Cell` using `rq.solve_steady_state`. Shows creating a `Cell` with multiple states and couplings, including using arrays for detuning and rabi frequency, and accessing the shape and axis labels of the solution's density matrix.

```python
atom = "Rb85"
g = rq.ground_state(atom)
e1 = rq.D2_excited(atom)
e2 = A_QState(6, 2, 2.5)

det = np.linspace(-1,1,11)
rabi = np.linspace(0.1, 1, 10)

RbCell_time = rq.Cell(atom, [g, e1, e2])
RbCell_time.add_coupling((g,e1), rabi_frequency=1, detuning=det, label="D1")
RbCell_time.add_coupling((e1, e2), rabi_frequency=rabi, detuning=1, label="upper")

sol = rq.solve_steady_state(RbCell_time)
print(sol.rho.shape)
print(sol.axis_labels)
```

--------------------------------

### Draw Level Diagram (Sensor)

Source: https://github.com/qtc-umd/rydiqule/blob/main/tests/testing_notebooks/Level_Diagram.ipynb

Generates a level diagram visualization for the previously initialized rydiqule Sensor object, including default dephasing if present.

```python
level_diagram = rq.draw_diagram(test_ss)
```

--------------------------------

### Initializing a rydiqule Cell with A_QState (Basic)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Cell_Basics.ipynb

Demonstrates the basic initialization of a `rydiqule.Cell` object for Rubidium-85 using two `A_QState` objects representing the ground (5S1/2) and first excited (5P1/2) states. It shows how to pass the atom string and a list of states to the constructor and verifies the states stored in the cell.

```python
g = A_QState(5, 0, 0.5)
e = A_QState(5, 1, 0.5)

Rb_Cell = rq.Cell("Rb85", [g, e])
print(Rb_Cell.states)
print(type(Rb_Cell.states[0]))
```

--------------------------------

### Comparing Rydiqule Initial Condition to Steady State (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Compares the default initial condition obtained from the `Solution` object to the steady-state solution calculated using the Hamiltonian at time t=0. It uses `get_time_hamiltonian` and `solve_steady_state` to show they match.

```python
print(sensor_time_norwa.get_time_hamiltonian(0))
print(rq.solve_steady_state(sensor_time_norwa).rho)
```

--------------------------------

### Defining Rb87 D2 States

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Sets up the excited (F'=0,1,2,3) and ground (F=1,2) states with their respective magnetic sublevels (mF) for a Rubidium-87 D2 spectroscopy simulation using Rydiqule.

```python
Fps = [0,1,2,3]
Fgs = [1,2]
e_states = [[('e',F,mF) for mF in range(-F,F+1)] for F in Fps]
print(e_states)
g_states = [[('g',F,mF) for mF in range(-F,F+1)] for F in Fgs]
print(g_states)
e_spec = ('e','all','all')
g_spec = ('g','all','all')
```

--------------------------------

### Checking Rydiqule Code Coverage (Shell)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/dev/tests.rst

Runs the test suite and generates a code coverage report for the 'rydiqule' package using the pytest-cov plugin. Requires the pytest-cov plugin to be installed.

```shell
pytest --cov=rydiqule
```

--------------------------------

### Plotting Doppler-free transmission

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_Heterodyne_Doppler.ipynb

Creates a plot of the transmission coefficient versus time using `matplotlib`. It labels the axes and sets the title to indicate that the result is from the Doppler-free simulation.

```python
fig, ax = plt.subplots()
ax.plot(time_sol.t, transmission)
ax.set_xlabel("time (us)")
ax.set_ylabel('transmission')
ax.set_title("Doppler-Free Solution")
```

--------------------------------

### Retrieving Observable Objects

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Obtains Rydiqule observable objects from the steady-state solution, representing quantities like the real and imaginary parts of the susceptibility, which correspond to phase shift/polarization rotation and absorption/ellipticity.

```python
susc_aligned = solF1F0sigNMOR.coupling_coefficient_observable(((1, 'all'), e))
susc_perp = solF1F0sigNMOR.get_observable(perp_obs)
```

--------------------------------

### Defining Sensor with State Manifolds - Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Defines ground and excited state manifolds using statespecs. Expands the excited state manifold into individual states. Initializes a `rydiqule.Sensor` object with these manifolds and prints the initial coupling graph nodes, which represent the defined states.

```python
g = (0,0)
e = (1, [-1,0,1])
[e1, e2, e3] = rq.expand_statespec(e)

sensor_man = rq.Sensor([g, e])
print(sensor_man.couplings.nodes)
```

--------------------------------

### Adding Decoherence and Transit Broadening

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Introduces relaxation processes between the excited and ground states (decoherence) and simulates the effect of atoms moving through the interaction region (transit broadening) on the system dynamics.

```python
cgg = {(e, (1,-1)): 1/3,
       (e, (1,0)): 1/3,
       (e, (1,1)): 1/3}
s.add_decoherence((e, g), 2*np.pi*6.0666, coupling_coefficients=cgg, label='F0_gamma')

s.add_transit_broadening(2*np.pi*0.1, repop={state:1/3 for state in s.states_with_spec(g)})
```

--------------------------------

### Building LaTeX Source for PDF Docs with Sphinx Shell

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/dev/docs.rst

The first command in a two-step process for building the PDF documentation, often used for more control or to replicate the readthedocs build process. This command generates the necessary LaTeX source files from the Sphinx documentation source. The output files are placed in the `docs/build/latex/` directory.

```shell
make latex
```

--------------------------------

### Defining Ladder System with rydiqule Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/intro_nbs/Introduction_To_Rydiqule.ipynb

Initializes a 3-state `rydiqule.Sensor` object and adds two laser couplings to form a ladder configuration. The couplings are defined using dictionaries specifying states, detuning, and Rabi frequency.

```python
ladder_sensor = rq.Sensor(3)
laser_01 = {"states": (0,1), "detuning": 1, "rabi_frequency": 3}
laser_12 = {"states": (1,2), "detuning": 2, "rabi_frequency": 5}
ladder_sensor.add_couplings(laser_01, laser_12)
```

--------------------------------

### Plotting Simulation Results with Matplotlib in Python

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Generates a plot of the imaginary part of the extracted susceptibility ('susc.imag') against the probe detuning ('dets') using matplotlib.pyplot. This visualizes the absorption spectrum of the atomic system.

```python
fig, ax = plt.subplots(1)

ax.plot(dets, susc.imag)
ax.set_xlabel('Probe Detuning (MHz)')
ax.set_ylabel('Probe Absorption (arb.)')
```

--------------------------------

### Extracting State Populations (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Retrieves the diagonal elements of the steady-state density matrix from the solution (solF1F0sig), which represent the populations of each atomic state. This allows analysis of how population is distributed among the states.

```python
pops = rq.get_rho_populations(solF1F0sig)
```

--------------------------------

### Get System Axis Labels

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/Saturated_Absorption_Spectroscopy.ipynb

Retrieves the axis labels defined for the rydiqule system object. These labels typically correspond to the scan parameters used in the simulation, such as laser detunings.

```python
s.axis_labels()
```

--------------------------------

### Run Rydiqule Observable Unit Tests (Shell)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/writeups/observables.rst

Execute the specific pytest unit tests related to Rydiqule's observable and experiment calculations from the package parent directory. Requires pytest dependencies to be installed.

```shell
pytest .\tests -m experiments
```

--------------------------------

### Import Rydiqule Library (Python)

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/3-photon_example.ipynb

Imports the main rydiqule library for simulating Rydberg atom systems and a utility function for extracting density matrix elements.

```python
import rydiqule as rq
from rydiqule.sensor_utils import get_rho_ij
```

--------------------------------

### Extracting Doppler-free transmission

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/RF_Heterodyne_Doppler.ipynb

Retrieves the calculated transmission coefficient over time from the `time_sol` object obtained from the Doppler-free simulation. This coefficient represents the probe laser transmission through the atomic vapor cell.

```python
transmission = time_sol.get_transmission_coef()
```

--------------------------------

### Plotting NMOR Spectroscopy Results

Source: https://github.com/qtc-umd/rydiqule/blob/main/docs/source/examples/NMOR_examples.ipynb

Generates plots to visualize the calculated observables (phase shift, absorption, polarization rotation, ellipticity) and state populations as a function of the applied Larmor frequency (magnetic field).

```python
fig, (ax, ax2, ax3) = plt.subplots(1, 3, figsize=(12, 3.5))

ax.plot(larmor_freqs, susc_aligned.real, label='Phase Shift')
ax.plot(larmor_freqs, susc_aligned.imag, label='Absorption')
ax.legend()
ax.set_xlabel('Larmor Frequency (MHz)')
ax.set_ylabel('Observable (arb.)')

ax2.plot(larmor_freqs, susc_perp.real,label='Pol. Rot.')
ax2.plot(larmor_freqs, susc_perp.imag, label='Ellip. Rot.')
ax2.legend()
ax2.set_xlabel('Larmor Frequency (MHz)')

ax3.plot(larmor_freqs, pops, label=s.states)
ax3.legend()
ax3.set_xlabel('Larmor Frequency (MHz)')
ax3.set_ylabel('Sub-level population (frac.)')
```