fixed latex equations in docs

Author: nathanielatom

.github/workflows/build.yml

@@ -46,9 +46,14 @@ jobs:
       - name: run tests
         run: |
           pytest
-      - name: build docs
+      - name: build wheel
         run: |
-          cd docs
+          mkdir dist
+          cd dist
+          python -m pip wheel .. --no-deps
+      - name: generate docs
+        run: |
+          cd ../docs
           make html
       - name: setup pages
         uses: actions/configure-pages@v5

docs/adiabatic_pulse_demo.rst

@@ -9,14 +9,15 @@ Adiabatic Pulse Example
     - numpy
     - scipy
     - bokeh
-    - https://github.com/nathanielatom/gigablochs
+    - gigablochs
 
 .. py-repl::
     :output: repl_output
 
     print("hallo world")
     import numpy as np
     import scipy.signal as sig
+    from bokeh.plotting import show
     from gigablochs import bloch, rf, flow
     print(bloch.GAMMA)
 

docs/conf.py

@@ -38,6 +38,7 @@
     'cupy': ('https://docs.cupy.dev/en/stable/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/', None),
     'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
+    'sympy': ('https://docs.sympy.org/latest/', None),
     'bokeh': ('https://docs.bokeh.org/en/latest/', None),
     'matplotlib': ('https://matplotlib.org/stable/', None),
     'manim': ('https://docs.manim.community/en/stable/', None),
@@ -52,30 +53,20 @@
 autosummary_generate = True
 default_role = 'py:obj'
 
-# # TODO: fix latex rendering of \gammabar, physics package not working
-# r"""
-# % define symbol \gammabar
-# \usepackage{stackengine}
-# \usepackage{scalerel}
-# \newcommand\gammabar{\ThisStyle{\ensurestackMath{%
-# \stackengine{-1.5\LMpt}{$$\SavedStyle\gamma$$}{$$\SavedStyle-$$}{O}{c}{F}{F}{L}}}}
-# """
-
-# # MathJax Latex equation settings
+# MathJax Latex equation settings
 mathjax3_config = {
     'tex': {
         'macros': {
-            'gammabar': r"""\ThisStyle{\ensurestackMath{\stackengine{-1.5\LMpt}{$$\SavedStyle\gamma$$}{$$\SavedStyle-$$}{O}{c}{F}{F}{L}}}""",
+            'gammabar': r'{\gamma\kern-0.55em\raise-0.25ex\hbox{--}}',
         },
-        'packages': {'[+]': ['ams', 'newcommand', 'configmacros', 'stackengine', 'scalerel', 'physics']},
+        'packages': {'[+]': ['physics']},
     },
     'loader': {
         'load': ['[tex]/physics'],
     }
 }
 
 # -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_book_theme'
 html_logo = "_static/gigablochs_logo_transparent.png"

gigablochs/bloch.py

@@ -52,12 +52,14 @@ def construct_B_field(rf_am, G=0, position=0, *, off_resonance=0, B1_sensitivity
     .. math::
 
         B_x = \\Delta B_1 \\Re{RF_{AM}}
+
         B_y = \\Delta B_1 \\Im{RF_{AM}}
-        B_z = G \\cdot r + \\frac{RF_{FM}}{\\gammabar} + \\frac{\\Delta f}{\\gammabar}
+
+        B_z = \\vec{G} \\cdot \\vec{r} + \\frac{RF_{FM}}{\\gammabar} + \\frac{\\Delta f}{\\gammabar}
 
     where :math:`B_x`, :math:`B_y`, and :math:`B_z` are the magnetic field components,
     :math:`\\Delta B_1` is the unitless B1 sensitivity factor, :math:`RF_{AM}` is the RF amplitude modulation waveform in Tesla,
-    :math:`G` is the gradient waveform in Tesla/m, :math:`r` is the spin's spatial position waveform in meters,
+    :math:`\\vec{G}` is the gradient waveform in Tesla/m, :math:`\\vec{r}` is the spin's spatial position waveform in meters,
     :math:`RF_{FM}` is the RF frequency modulation waveform in Hz, :math:`\\gammabar` is the reduced gyromagnetic ratio in Hz/T,
     and :math:`\\Delta f` is the off-resonance frequency in Hz.
 

gigablochs/rf.py

@@ -33,11 +33,11 @@ def sinc_pulse(flip_angle, duration, bandwidth, dt, phase_angle=0, window='hann'
 
     .. math::
 
-            \\theta = \\gamma \\int B_1 dt
+            \\theta = \\gamma \\int_0^T B_1 dt
 
-        where :math:`\\theta` is the flip angle, :math:`\\gamma` is the gyromagnetic
-        ratio, and :math:`B_1` is the pulse amplitude. The sinc pulse is normalized
-        to achieve the desired flip angle.
+    where :math:`\\theta` is the flip angle in rads, :math:`\\gamma` is the gyromagnetic
+    ratio in rads/s/T, :math:`T` is the pulse duration is s, and :math:`B_1` is the pulse
+    amplitude in T. The sinc pulse is normalized to achieve the desired flip angle.
 
     """
     theta, alpha = np.deg2rad(phase_angle), np.deg2rad(flip_angle)
@@ -73,14 +73,13 @@ def adiabaticity(pulse_am, pulse_fm, dt):
 
     .. math::
 
-        K = \\frac{\\left | \\gamma B_{\\mathrm{effective}} \\right |}{\\left | \\dv{\\varphi}{t} \\right |} = \\frac{\\gamma\\sqrt{A^2(t) + \\left ( B_0 - \\frac{\\omega(t)}{\\gamma} \\right )^2}}{\\dv{}{t}\\left ( \\arctan(\\frac{A(t)}{B_0 - \\frac{\\omega(t)}{\\gamma}}) \\right )}
+        K = \\frac{\\left | \\gamma B_{\\mathrm{effective}} \\right |}{\\left | \\dv{\\varphi}{t} \\right |} = \\frac{\\gamma\\sqrt{A^2(t) + \\left (\\frac{f(t)}{\\gammabar} \\right )^2}}{\\left| \\dv{}{t}\\left ( \\arctan(\\frac{\\gammabar A(t)}{f(t)}) \\right ) \\right|}
 
-    where :math:`A(t)` and :math:`\\omega(t)` are the amplitude and frequency
-    modulation waveforms, respectively, and :math:`B_0` is the static magnetic
-    field. The adiabaticity is a measure of the ability of the pulse to drive
-    the magnetization to follow the instantaneous effective magnetic field in
-    the rotating frame. When the adiabaticity is much greater than 1, for all
-    time, the pulse is considered adiabatic.
+    where :math:`A(t)` and :math:`f(t)` are the amplitude and frequency
+    modulation waveforms, respectively. The adiabaticity is a measure of the
+    ability of the pulse to drive the magnetization to follow the
+    instantaneous effective magnetic field in the rotating frame. When the
+    adiabaticity is much greater than 1, for all time, the pulse is considered adiabatic.
 
     """
     Bz_eff = pulse_fm / bloch.GAMMA_BAR

gigablochs/utils.py

@@ -109,7 +109,7 @@ def rodrigues_rotation(v, k, theta, *, normalize=True, axis=-1):
 
     .. math::
 
-        v_{\\text{rot}} = v \\cos(\\theta) + (k \\times v) \\sin(\\theta) + k (k \\cdot v) (1 - \\cos(\\theta))
+        v_{\\text{rot}} = v \\cos\\theta + (k \\times v) \\sin\\theta + k (k \\cdot v) (1 - \\cos\\theta)
 
     where :math:`v_{\\text{rot}}` is the rotated vector, :math:`v` is the original vector, :math:`k` is the rotation axis,
     and :math:`\\theta` is the rotation angle.