Updated Documentation

.github/workflows/Build_Deploy_Docs.yml

@@ -28,6 +28,7 @@ jobs:
         run: poetry run sphinx-build -b html docsrc/ docsrc/_build/html > sphinx_build.log 2>&1
       - name: Upload build log
         uses: actions/upload-artifact@v4.6.2
+        if: always()
         with:
           name: sphinx-build-log
           path: sphinx_build.log

.github/workflows/TestBuild_Docs.yml

@@ -0,0 +1,39 @@
+name: Test Build Docs
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install Poetry
+        run: |
+          curl -sSL https://install.python-poetry.org | python -
+          echo "${HOME}/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: poetry install --with doc
+
+      - name: Build documentation
+        run: poetry run sphinx-build -b html docsrc/ docsrc/_build/html > sphinx_build.log 2>&1
+      - name: Upload build log
+        uses: actions/upload-artifact@v4.6.2
+        if: always()
+        with:
+          name: sphinx-build-log
+          path: sphinx_build.log
+

.gitignore

@@ -105,6 +105,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+.venv*
 
 # Spyder project settings
 .spyderproject
@@ -125,3 +126,7 @@ dmypy.json
 .pyre/
 
 .DS_Store
+
+poetry.lock
+
+docsrc/auto_examples/

citation.rst

@@ -0,0 +1,39 @@
+Citation
+--------
+
+Citation of scientific software is important to give credit to the developers and to help track the impact of the software in research.
+
+To cite PyEPR in publications, please currently use the Zenodo general DOI:
+
+.. image:: https://zenodo.org/badge/888368760.svg
+   :target: https://doi.org/10.5281/zenodo.17107010
+   :alt: DOI
+
+Specific PyEPR versions will also have uniquie DOIs that can be found on the respective Zenodo release page.
+The associated Zotero entry is available `here <https://doi.org/10.5281/zenodo.17107010>`_.
+
+A paper describing PyEPR is currently in preparation and will be linked here once published.
+
+Bibtex Entry
+++++++++++++
+
+.. code-block:: bibtex
+
+  @software{pyepr_2025,
+    author       = {Hugo, Karas and
+                    Jeschke, Gunnar and
+                    Stoll, Stefan},
+    title        = {JeschkeLab/PyEPR: Version 1.0},
+    month        = sep,
+    year         = 2025,
+    publisher    = {Zenodo},
+    version      = {v1.0},
+    doi          = {10.5281/zenodo.17107011},
+    url          = {https://doi.org/10.5281/zenodo.17107011},
+    swhid        = {swh:1:dir:d3ae7fdd8041eb365003ea3e40db8bbb31a6c741
+                    ;origin=https://doi.org/10.5281/zenodo.17107010;vi
+                    sit=swh:1:snp:5c1894da8cabcaf89397959130c3ff4badea
+                    5b87;anchor=swh:1:rel:316cb6fc9c055bd7058460f5559a
+                    8342d326ebd4;path=JeschkeLab-PyEPR-c194a75
+                    },
+  }

docsrc/API_docs.rst

@@ -19,6 +19,7 @@ Analysis Modules
 .. autoapisummary::
 
    pyepr.FieldSweepAnalysis
+   pyepr.HahnEchoRelaxationAnalysis
    pyepr.ResonatorProfileAnalysis
    pyepr.CarrPurcellAnalysis
    pyepr.ReptimeAnalysis
@@ -29,7 +30,7 @@ Sequences
 .. autoapisummary::
 
    pyepr.sequences.HahnEchoSequence
-   pyepr.sequences.T2RelaxationSequence
+   pyepr.sequences.HahnEchoRelaxationSequence
    pyepr.sequences.FieldSweepSequence
    pyepr.sequences.ReptimeScan
    pyepr.sequences.CarrPurcellSequence
@@ -44,7 +45,6 @@ Pulses
 
    pyepr.pulses.Pulse
    pyepr.pulses.Detection
-   pyepr.pulses.Delay
    pyepr.pulses.RectPulse
    pyepr.pulses.GaussianPulse
    pyepr.pulses.HSPulse

docsrc/README.md

@@ -0,0 +1,6 @@
+
+
+To build the documentation and serve it with live reloading, run:
+```
+sphinx-autobuild docsrc docsrc/_build/html
+```

docsrc/citation.rst

@@ -0,0 +1 @@
+.. include:: ../citation.rst

docsrc/conf.py

@@ -21,13 +21,16 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = ['sphinx.ext.viewcode',
+              'sphinx_design',
+              'myst_parser',
               'sphinx.ext.intersphinx',
               'autoapi.extension',
               'sphinx_toolbox.collapse',
               'sphinx_toolbox.code',
               'sphinx_copybutton',
               'numpydoc',
-              'sphinx_favicon']
+              'sphinx_favicon',
+              'sphinx_gallery.gen_gallery']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
@@ -44,6 +47,10 @@
 autoapi_python_use_implicit_namespaces = True
 autoapi_own_page_level = 'class'
 
+sphinx_gallery_conf = {
+     'examples_dirs': 'examples',   # path to your example scripts
+     'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docsrc/examples/GALLERY_HEADER.rst

@@ -0,0 +1,4 @@
+PyEPR Example Scripts
+=====================
+
+Work in Progress: This gallery is under construction and will be expanded with more examples in the future.

docsrc/examples/config_files/BrukerElexSys_config.yaml

@@ -0,0 +1,22 @@
+Spectrometer:
+  Type: Complete Spectrometer
+  Manufacturer: Bruker
+  Model: E580
+  Local Name: Bruker E580
+
+  AWG: True
+
+
+  Bridge:
+    Min Freq: 33 #GHz
+    Max Freq: 35 #GHz
+    Digital Source: False # Analogue or Digital Source (for Q-band standalone)
+    d0: 650 #ns
+    Sample Freq: 1 # GSa/s
+    DutyCycle: 3 # Max amplifier duty cycle %
+    Pulse dt: 2  #ns
+    Det dt: 0.5  #ns
+    Det res: 8  #bit
+    Video BW: 125 #MHz on VAMP-III this changes the time base
+    On Board Pcyc: False # Use on-board phase cycling generally
+    On Board Pcyc (EDFS): True  # Use on-board phase cycling for EDFS experiments

docsrc/examples/config_files/Dummy_config.yaml

@@ -0,0 +1,20 @@
+Spectrometer:
+  Type: Complete Spectrometer
+  Manufacturer: Dummy
+  Model: DummyV1
+  Local Name: Dummy
+
+  AWG: True
+
+  Bridge:
+    Min Freq: 33 #GHz
+    Max Freq: 35 #GHz
+    Sample Freq: 8 #GSa/s
+    Det Freq: 2 #GSa/s
+    Det Res: 12  #bit
+
+  Dummy:
+    speedup: 1000 # Default: 100
+    SNR: 150
+    ESEEM_depth: 0.15
+    noise_level: 0.005

docsrc/examples/config_files/ETHmatlab_config.yaml

@@ -0,0 +1,16 @@
+Spectrometer:
+  Type: Complete Spectrometer
+  Manufacturer: ETH
+  Model: Matlab
+  Local Name: F243_AWG
+
+  AWG: True
+
+  Bridge:
+    Min Freq: 33 #GHz
+    Max Freq: 36 #GHz
+    Sample Freq: 8 # GSa/s
+    Det Freq: 2 #GSa/s
+    Det Res: 12  #bit
+
+  Waveform Precision: 1 #ns

docsrc/index.rst

@@ -15,16 +15,17 @@ PyEPR's Key Features
 
 - Fully python based, open-source and free to use
 - Intuitive object-oriented pulse sequencer
-- Pre-defined common EPR experiments (CW, Hahn Echo, Inversion Recovery, Carr-Purcell, DEER, etc.)
+- Pre-defined common EPR experiments (CW, Hahn Echo, Inversion Recovery, Carr-Purcell, etc.)
 - Easy to define custom experiments
 - Pre-defined common pulse shapes (rectangular, Gaussian, sech/tanh, etc.)
 - Easy to define custom pulse shapes
 - Hardware abstraction layer for interfacing with different spectrometers
 - BRUKER PulseSpel compiler from PyEPR sequences
 
-.. warning:: 
-    PyEPR is an actively developed software package, that is still very much a work in process. Please consider this to be a beta release.
-
+.. image:: _static/Hardware_Interface_Diagram.svg
+    :align: center
+    :width: 90%
+
 .. toctree::
     :maxdepth: 1
     :hidden:
@@ -39,8 +40,10 @@ PyEPR's Key Features
     :caption: About
 
     ./releasenotes.rst
-    ./contributing.rst
+    citation.rst
+    licence.rst
     Github <https://github.com/JeschkeLab/PyEPR>
     autoDEER <https://github.com/JeschkeLab/autoDEER>
+
 
 

docsrc/install.rst

@@ -20,5 +20,23 @@ or with poetry:
 To install PyEPR from source, clone the repository and run the following command:
 
 .. code-block:: bash
+
+    git clone https://github.com/JeschkeLab/PyEPR
 
     pip install .
+
+Requirements
+++++++++++++
+
+PyEPR requires:
+    - Python >= 3.11 < 3.13
+    - Numpy 
+    - Scipy
+    - Matplotlib
+    - pyyaml
+    - xarray
+    - h5netcdf
+    - toml
+    - deerlab (https://github.com/JeschkeLab/DeerLab)
+    - numba
+    - psutil

docsrc/licence.rst

@@ -0,0 +1,4 @@
+License
+-------
+
+.. literalinclude:: ../LICENSE

docsrc/sg_execution_times.rst

@@ -0,0 +1,37 @@
+
+:orphan:
+
+.. _sphx_glr_sg_execution_times:
+
+
+Computation times
+=================
+**00:00.000** total execution time for 0 files **from all galleries**:
+
+.. container::
+
+  .. raw:: html
+
+    <style scoped>
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/5.3.0/css/bootstrap.min.css" rel="stylesheet" />
+    <link href="https://cdn.datatables.net/1.13.6/css/dataTables.bootstrap5.min.css" rel="stylesheet" />
+    </style>
+    <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/dataTables.bootstrap5.min.js"></script>
+    <script type="text/javascript" class="init">
+    $(document).ready( function () {
+        $('table.sg-datatable').DataTable({order: [[1, 'desc']]});
+    } );
+    </script>
+
+  .. list-table::
+   :header-rows: 1
+   :class: table table-striped sg-datatable
+
+   * - Example
+     - Time
+     - Mem (MB)
+   * - N/A
+     - N/A
+     - N/A