From 245063c7bb9d7698521bb11c73bbc10dd2b94e87 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 15 Dec 2025 20:08:31 -0500 Subject: [PATCH 01/25] init sphinx --- .gitignore | 1 + doc/Makefile | 20 ++++++++++++++++++++ doc/make.bat | 35 +++++++++++++++++++++++++++++++++++ doc/placeholder | 0 doc/source/conf.py | 28 ++++++++++++++++++++++++++++ doc/source/index.rst | 17 +++++++++++++++++ 6 files changed, 101 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/make.bat delete mode 100644 doc/placeholder create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/.gitignore b/.gitignore index 47650c0e..44b61695 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ PyORBIT.egg-info *.so .*.swp .eggs +.venv diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/placeholder b/doc/placeholder deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..83bb65fd --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'PyORBIT3' +copyright = '2025, PyORBIT Collaboration' +author = 'PyORBIT Collaboration' +release = 'v3.0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..dfd70787 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,17 @@ +.. PyORBIT3 documentation master file, created by + sphinx-quickstart on Mon Dec 15 20:07:23 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +PyORBIT3 documentation +====================== + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + From 12c9437996be38e2b7f929c6d143d69dda228c13 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 15 Dec 2025 20:19:03 -0500 Subject: [PATCH 02/25] sphinx-apidoc first pass --- doc/source/conf.py | 18 +++-- doc/source/index.rst | 41 +++++++++++- doc/source/modules/orbit.aperture.rst | 31 +++++++++ doc/source/modules/orbit.bumps.rst | 31 +++++++++ doc/source/modules/orbit.bunch_generators.rst | 19 ++++++ doc/source/modules/orbit.bunch_utils.rst | 25 +++++++ doc/source/modules/orbit.collimation.rst | 25 +++++++ doc/source/modules/orbit.core.rst | 10 +++ doc/source/modules/orbit.diagnostics.rst | 37 +++++++++++ doc/source/modules/orbit.errors.rst | 25 +++++++ doc/source/modules/orbit.fieldtracker.rst | 25 +++++++ doc/source/modules/orbit.foils.rst | 25 +++++++ doc/source/modules/orbit.impedances.rst | 25 +++++++ doc/source/modules/orbit.injection.rst | 43 ++++++++++++ doc/source/modules/orbit.kickernodes.rst | 37 +++++++++++ doc/source/modules/orbit.lattice.rst | 37 +++++++++++ doc/source/modules/orbit.matching.rst | 19 ++++++ doc/source/modules/orbit.matrix_lattice.rst | 25 +++++++ doc/source/modules/orbit.orbit_correction.rst | 19 ++++++ doc/source/modules/orbit.parsers.rst | 37 +++++++++++ doc/source/modules/orbit.py_linac.errors.rst | 19 ++++++ doc/source/modules/orbit.py_linac.lattice.rst | 61 +++++++++++++++++ .../orbit.py_linac.lattice_modifications.rst | 49 ++++++++++++++ .../modules/orbit.py_linac.linac_parsers.rst | 25 +++++++ .../modules/orbit.py_linac.materials.rst | 19 ++++++ .../orbit.py_linac.orbit_correction.rst | 19 ++++++ .../orbit.py_linac.overlapping_fields.rst | 31 +++++++++ .../orbit.py_linac.rf_field_readers.rst | 25 +++++++ doc/source/modules/orbit.py_linac.rst | 25 +++++++ doc/source/modules/orbit.rf_cavities.rst | 25 +++++++ doc/source/modules/orbit.rst | 42 ++++++++++++ .../orbit.space_charge.directforce2p5d.rst | 25 +++++++ doc/source/modules/orbit.space_charge.rst | 43 ++++++++++++ .../modules/orbit.space_charge.sc1d.rst | 25 +++++++ .../orbit.space_charge.sc2dslicebyslice.rst | 25 +++++++ .../modules/orbit.space_charge.sc2p5d.rst | 25 +++++++ .../modules/orbit.space_charge.sc3d.rst | 25 +++++++ doc/source/modules/orbit.teapot.rst | 25 +++++++ doc/source/modules/orbit.teapot_base.rst | 10 +++ doc/source/modules/orbit.time_dep.rst | 25 +++++++ doc/source/modules/orbit.utils.fitting.rst | 49 ++++++++++++++ .../modules/orbit.utils.orbit_mpi_utils.rst | 37 +++++++++++ doc/source/modules/orbit.utils.rst | 65 +++++++++++++++++++ doc/source/modules/orbit.utils.xml.rst | 19 ++++++ 44 files changed, 1287 insertions(+), 5 deletions(-) create mode 100644 doc/source/modules/orbit.aperture.rst create mode 100644 doc/source/modules/orbit.bumps.rst create mode 100644 doc/source/modules/orbit.bunch_generators.rst create mode 100644 doc/source/modules/orbit.bunch_utils.rst create mode 100644 doc/source/modules/orbit.collimation.rst create mode 100644 doc/source/modules/orbit.core.rst create mode 100644 doc/source/modules/orbit.diagnostics.rst create mode 100644 doc/source/modules/orbit.errors.rst create mode 100644 doc/source/modules/orbit.fieldtracker.rst create mode 100644 doc/source/modules/orbit.foils.rst create mode 100644 doc/source/modules/orbit.impedances.rst create mode 100644 doc/source/modules/orbit.injection.rst create mode 100644 doc/source/modules/orbit.kickernodes.rst create mode 100644 doc/source/modules/orbit.lattice.rst create mode 100644 doc/source/modules/orbit.matching.rst create mode 100644 doc/source/modules/orbit.matrix_lattice.rst create mode 100644 doc/source/modules/orbit.orbit_correction.rst create mode 100644 doc/source/modules/orbit.parsers.rst create mode 100644 doc/source/modules/orbit.py_linac.errors.rst create mode 100644 doc/source/modules/orbit.py_linac.lattice.rst create mode 100644 doc/source/modules/orbit.py_linac.lattice_modifications.rst create mode 100644 doc/source/modules/orbit.py_linac.linac_parsers.rst create mode 100644 doc/source/modules/orbit.py_linac.materials.rst create mode 100644 doc/source/modules/orbit.py_linac.orbit_correction.rst create mode 100644 doc/source/modules/orbit.py_linac.overlapping_fields.rst create mode 100644 doc/source/modules/orbit.py_linac.rf_field_readers.rst create mode 100644 doc/source/modules/orbit.py_linac.rst create mode 100644 doc/source/modules/orbit.rf_cavities.rst create mode 100644 doc/source/modules/orbit.rst create mode 100644 doc/source/modules/orbit.space_charge.directforce2p5d.rst create mode 100644 doc/source/modules/orbit.space_charge.rst create mode 100644 doc/source/modules/orbit.space_charge.sc1d.rst create mode 100644 doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst create mode 100644 doc/source/modules/orbit.space_charge.sc2p5d.rst create mode 100644 doc/source/modules/orbit.space_charge.sc3d.rst create mode 100644 doc/source/modules/orbit.teapot.rst create mode 100644 doc/source/modules/orbit.teapot_base.rst create mode 100644 doc/source/modules/orbit.time_dep.rst create mode 100644 doc/source/modules/orbit.utils.fitting.rst create mode 100644 doc/source/modules/orbit.utils.orbit_mpi_utils.rst create mode 100644 doc/source/modules/orbit.utils.rst create mode 100644 doc/source/modules/orbit.utils.xml.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 83bb65fd..12246764 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,6 +3,12 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +# -- Path setup -------------------------------------------------------------- +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -14,15 +20,19 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] +autosummary_generate = True +napoleon_numpy_docstring = True templates_path = ['_templates'] exclude_patterns = [] - - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' +html_theme = 'furo' html_static_path = ['_static'] +html_show_source_link = True +html_theme_options = { + # 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', +} diff --git a/doc/source/index.rst b/doc/source/index.rst index dfd70787..d16735f7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,5 +13,44 @@ documentation for details. .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Modules + :hidden: + modules/orbit.aperture + modules/orbit.bump + modules/orbit.bunch_generators + modules/orbit.bunch_utils + modules/orbit.collimation + modules/orbit.diagnostics + modules/orbit.errors + modules/orbit.fieldtracker + modules/orbit.foils + modules/orbit.impedances + modules/orbit.injection + modules/orbit.kickernodes + modules/orbit.lattice + modules/orbit.matching + modules/orbit.matrix_lattice + modules/orbit.orbit_correction + modules/orbit.parsers + modules/orbit.py_linac.errors + modules/orbit.py_linac.lattice + modules/orbit.py_linac.lattice_modifications + modules/orbit.py_linac.linac_parsers + modules/orbit.py_linac.materials + modules/orbit.py_linac.orbit_correction + modules/orbit.py_linac.overlapping_fields + modules/orbit.py_linac.rf_field_readers + modules/orbit.py_linac + modules/orbit.rf_cavities + modules/orbit.space_charge.directforce2p5d + modules/orbit.space_charge + modules/orbit.space_charge.sc1d + modules/orbit.space_charge.sc2dslicebyslice + modules/orbit.space_charge.sc2p5d + modules/orbit.space_charge.sc3d + modules/orbit.teapot + modules/orbit.teapot_base + modules/orbit.time_dep + modules/orbit.utils.fitting + modules/orbit.utils.orbit_mpi_utils diff --git a/doc/source/modules/orbit.aperture.rst b/doc/source/modules/orbit.aperture.rst new file mode 100644 index 00000000..9cf8d713 --- /dev/null +++ b/doc/source/modules/orbit.aperture.rst @@ -0,0 +1,31 @@ +orbit.aperture package +====================== + +Submodules +---------- + + +.. automodule:: orbit.aperture.ApertureLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.aperture.ApertureLatticeRangeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.aperture.TeapotApertureNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.aperture + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bumps.rst b/doc/source/modules/orbit.bumps.rst new file mode 100644 index 00000000..639b975e --- /dev/null +++ b/doc/source/modules/orbit.bumps.rst @@ -0,0 +1,31 @@ +orbit.bumps package +=================== + +Submodules +---------- + + +.. automodule:: orbit.bumps.BumpLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bumps.TeapotBumpNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bumps.bumps + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bumps + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bunch_generators.rst b/doc/source/modules/orbit.bunch_generators.rst new file mode 100644 index 00000000..d2aae682 --- /dev/null +++ b/doc/source/modules/orbit.bunch_generators.rst @@ -0,0 +1,19 @@ +orbit.bunch\_generators package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.bunch_generators.distribution_generators + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bunch_generators + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bunch_utils.rst b/doc/source/modules/orbit.bunch_utils.rst new file mode 100644 index 00000000..35d80b35 --- /dev/null +++ b/doc/source/modules/orbit.bunch_utils.rst @@ -0,0 +1,25 @@ +orbit.bunch\_utils package +========================== + +Submodules +---------- + + +.. automodule:: orbit.bunch_utils.particleidnumber + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bunch_utils.serialize + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bunch_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.collimation.rst b/doc/source/modules/orbit.collimation.rst new file mode 100644 index 00000000..b6100fdb --- /dev/null +++ b/doc/source/modules/orbit.collimation.rst @@ -0,0 +1,25 @@ +orbit.collimation package +========================= + +Submodules +---------- + + +.. automodule:: orbit.collimation.TeapotCollimatorNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.collimation.collimationLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.collimation + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.core.rst b/doc/source/modules/orbit.core.rst new file mode 100644 index 00000000..53921b7d --- /dev/null +++ b/doc/source/modules/orbit.core.rst @@ -0,0 +1,10 @@ +orbit.core package +================== + +Module contents +--------------- + +.. automodule:: orbit.core + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.diagnostics.rst b/doc/source/modules/orbit.diagnostics.rst new file mode 100644 index 00000000..454b5406 --- /dev/null +++ b/doc/source/modules/orbit.diagnostics.rst @@ -0,0 +1,37 @@ +orbit.diagnostics package +========================= + +Submodules +---------- + + +.. automodule:: orbit.diagnostics.TeapotDiagnosticsNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.diagnostics + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.diagnosticsLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.profiles + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.diagnostics + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.errors.rst b/doc/source/modules/orbit.errors.rst new file mode 100644 index 00000000..8ff1deb7 --- /dev/null +++ b/doc/source/modules/orbit.errors.rst @@ -0,0 +1,25 @@ +orbit.errors package +==================== + +Submodules +---------- + + +.. automodule:: orbit.errors.ErrorLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.errors.ErrorNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.errors + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.fieldtracker.rst b/doc/source/modules/orbit.fieldtracker.rst new file mode 100644 index 00000000..bba5190f --- /dev/null +++ b/doc/source/modules/orbit.fieldtracker.rst @@ -0,0 +1,25 @@ +orbit.fieldtracker package +========================== + +Submodules +---------- + + +.. automodule:: orbit.fieldtracker.TeapotFieldLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.fieldtracker.TeapotFieldTrackerNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.fieldtracker + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.foils.rst b/doc/source/modules/orbit.foils.rst new file mode 100644 index 00000000..6d1c11b4 --- /dev/null +++ b/doc/source/modules/orbit.foils.rst @@ -0,0 +1,25 @@ +orbit.foils package +=================== + +Submodules +---------- + + +.. automodule:: orbit.foils.TeapotFoilNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.foils.foilLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.foils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.impedances.rst b/doc/source/modules/orbit.impedances.rst new file mode 100644 index 00000000..4c540fb2 --- /dev/null +++ b/doc/source/modules/orbit.impedances.rst @@ -0,0 +1,25 @@ +orbit.impedances package +======================== + +Submodules +---------- + + +.. automodule:: orbit.impedances.ImpedanceLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.impedances.ImpedanceNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.impedances + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.injection.rst b/doc/source/modules/orbit.injection.rst new file mode 100644 index 00000000..f5b4963e --- /dev/null +++ b/doc/source/modules/orbit.injection.rst @@ -0,0 +1,43 @@ +orbit.injection package +======================= + +Submodules +---------- + + +.. automodule:: orbit.injection.InjectionLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.TeapotInjectionNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.distributions + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.injectparticles + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.joho + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.injection + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.kickernodes.rst b/doc/source/modules/orbit.kickernodes.rst new file mode 100644 index 00000000..2b000f0b --- /dev/null +++ b/doc/source/modules/orbit.kickernodes.rst @@ -0,0 +1,37 @@ +orbit.kickernodes package +========================= + +Submodules +---------- + + +.. automodule:: orbit.kickernodes.KickerLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.TeapotKickerNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.kicker + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.waveforms + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.kickernodes + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.lattice.rst b/doc/source/modules/orbit.lattice.rst new file mode 100644 index 00000000..68ed9568 --- /dev/null +++ b/doc/source/modules/orbit.lattice.rst @@ -0,0 +1,37 @@ +orbit.lattice package +===================== + +Submodules +---------- + + +.. automodule:: orbit.lattice.AccActionsContainer + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccLattice + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccNodeBunchTracker + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.matching.rst b/doc/source/modules/orbit.matching.rst new file mode 100644 index 00000000..020f4937 --- /dev/null +++ b/doc/source/modules/orbit.matching.rst @@ -0,0 +1,19 @@ +orbit.matching package +====================== + +Submodules +---------- + + +.. automodule:: orbit.matching.matching + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.matching + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.matrix_lattice.rst b/doc/source/modules/orbit.matrix_lattice.rst new file mode 100644 index 00000000..b88fc3c4 --- /dev/null +++ b/doc/source/modules/orbit.matrix_lattice.rst @@ -0,0 +1,25 @@ +orbit.matrix\_lattice package +============================= + +Submodules +---------- + + +.. automodule:: orbit.matrix_lattice.BaseMATRIX + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.matrix_lattice.MATRIX_Lattice + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.matrix_lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.orbit_correction.rst b/doc/source/modules/orbit.orbit_correction.rst new file mode 100644 index 00000000..87d458d1 --- /dev/null +++ b/doc/source/modules/orbit.orbit_correction.rst @@ -0,0 +1,19 @@ +orbit.orbit\_correction package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.orbit_correction.orbit_correction + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.orbit_correction + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.parsers.rst b/doc/source/modules/orbit.parsers.rst new file mode 100644 index 00000000..8fffb512 --- /dev/null +++ b/doc/source/modules/orbit.parsers.rst @@ -0,0 +1,37 @@ +orbit.parsers package +===================== + +Submodules +---------- + + +.. automodule:: orbit.parsers.field_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.mad_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.madx_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.sad_parser + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.parsers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.errors.rst b/doc/source/modules/orbit.py_linac.errors.rst new file mode 100644 index 00000000..304668e5 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.errors.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.errors package +============================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.errors.ErrorNodesAndControllersLib + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.errors + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice.rst b/doc/source/modules/orbit.py_linac.lattice.rst new file mode 100644 index 00000000..08f273fb --- /dev/null +++ b/doc/source/modules/orbit.py_linac.lattice.rst @@ -0,0 +1,61 @@ +orbit.py\_linac.lattice package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.lattice.LinacAccLatticeFunc + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacAccLatticeLib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacApertureNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacDiagnosticsNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacFieldOverlappingNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacRfGapNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacTransportMatrixGenNodes + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice_modifications.rst b/doc/source/modules/orbit.py_linac.lattice_modifications.rst new file mode 100644 index 00000000..a04b7547 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.lattice_modifications.rst @@ -0,0 +1,49 @@ +orbit.py\_linac.lattice\_modifications package +============================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.lattice_modifications.apertures_additions_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.errors_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.quad_overlap_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.rf_models_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.rf_quad_overlap_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.sns_aperture_additions + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.lattice_modifications + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.linac_parsers.rst b/doc/source/modules/orbit.py_linac.linac_parsers.rst new file mode 100644 index 00000000..32e83a62 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.linac_parsers.rst @@ -0,0 +1,25 @@ +orbit.py\_linac.linac\_parsers package +====================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.linac_parsers.jparc_linac_lattice_factory + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.linac_parsers.sns_linac_lattice_factory + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.linac_parsers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.materials.rst b/doc/source/modules/orbit.py_linac.materials.rst new file mode 100644 index 00000000..f777efb7 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.materials.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.materials package +================================= + +Submodules +---------- + + +.. automodule:: orbit.py_linac.materials.VacuumWindowLinacNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.materials + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.orbit_correction.rst b/doc/source/modules/orbit.py_linac.orbit_correction.rst new file mode 100644 index 00000000..1ef126e2 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.orbit_correction.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.orbit\_correction package +========================================= + +Submodules +---------- + + +.. automodule:: orbit.py_linac.orbit_correction.transport_lines_orbit_correction + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.orbit_correction + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.overlapping_fields.rst b/doc/source/modules/orbit.py_linac.overlapping_fields.rst new file mode 100644 index 00000000..9792294c --- /dev/null +++ b/doc/source/modules/orbit.py_linac.overlapping_fields.rst @@ -0,0 +1,31 @@ +orbit.py\_linac.overlapping\_fields package +=========================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.overlapping_fields.jparc_enge_func_factory + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.overlapping_fields.overlapping_quad_fields_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.overlapping_fields.sns_enge_func_factory + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.overlapping_fields + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rf_field_readers.rst b/doc/source/modules/orbit.py_linac.rf_field_readers.rst new file mode 100644 index 00000000..1e48280c --- /dev/null +++ b/doc/source/modules/orbit.py_linac.rf_field_readers.rst @@ -0,0 +1,25 @@ +orbit.py\_linac.rf\_field\_readers package +========================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.rf_field_readers.RF_AxisFieldAnalysis + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.rf_field_readers.SuperFish_3D_RF_FieldReader + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.rf_field_readers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rst b/doc/source/modules/orbit.py_linac.rst new file mode 100644 index 00000000..2678c9f4 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.rst @@ -0,0 +1,25 @@ +orbit.py\_linac package +======================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.py_linac.errors + orbit.py_linac.lattice + orbit.py_linac.lattice_modifications + orbit.py_linac.linac_parsers + orbit.py_linac.materials + orbit.py_linac.orbit_correction + orbit.py_linac.overlapping_fields + orbit.py_linac.rf_field_readers + +Module contents +--------------- + +.. automodule:: orbit.py_linac + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.rf_cavities.rst b/doc/source/modules/orbit.rf_cavities.rst new file mode 100644 index 00000000..c41364a8 --- /dev/null +++ b/doc/source/modules/orbit.rf_cavities.rst @@ -0,0 +1,25 @@ +orbit.rf\_cavities package +========================== + +Submodules +---------- + + +.. automodule:: orbit.rf_cavities.RFLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.rf_cavities.RFNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.rf_cavities + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.rst b/doc/source/modules/orbit.rst new file mode 100644 index 00000000..baa4ca2e --- /dev/null +++ b/doc/source/modules/orbit.rst @@ -0,0 +1,42 @@ +orbit package +============= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.aperture + orbit.bumps + orbit.bunch_generators + orbit.bunch_utils + orbit.collimation + orbit.core + orbit.diagnostics + orbit.errors + orbit.fieldtracker + orbit.foils + orbit.impedances + orbit.injection + orbit.kickernodes + orbit.lattice + orbit.matching + orbit.matrix_lattice + orbit.orbit_correction + orbit.parsers + orbit.py_linac + orbit.rf_cavities + orbit.space_charge + orbit.teapot + orbit.teapot_base + orbit.time_dep + orbit.utils + +Module contents +--------------- + +.. automodule:: orbit + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.directforce2p5d.rst b/doc/source/modules/orbit.space_charge.directforce2p5d.rst new file mode 100644 index 00000000..fd68e4b0 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.directforce2p5d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.directforce2p5d package +=========================================== + +Submodules +---------- + + +.. automodule:: orbit.space_charge.directforce2p5d.directforceAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.directforce2p5d.directforceLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.directforce2p5d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.rst b/doc/source/modules/orbit.space_charge.rst new file mode 100644 index 00000000..1e6c9931 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.rst @@ -0,0 +1,43 @@ +orbit.space\_charge package +=========================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.space_charge.directforce2p5d + orbit.space_charge.sc1d + orbit.space_charge.sc2dslicebyslice + orbit.space_charge.sc2p5d + orbit.space_charge.sc3d + +Submodules +---------- + + +.. automodule:: orbit.space_charge.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sccenteredLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc1d.rst b/doc/source/modules/orbit.space_charge.sc1d.rst new file mode 100644 index 00000000..fc98d94d --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc1d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc1d package +================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc1d.sc1DNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc1d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc1d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst new file mode 100644 index 00000000..b20b40a6 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc2dslicebyslice package +============================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc2dslicebyslice.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc2dslicebyslice.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc2dslicebyslice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2p5d.rst b/doc/source/modules/orbit.space_charge.sc2p5d.rst new file mode 100644 index 00000000..50c704d3 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc2p5d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc2p5d package +================================== + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc2p5d.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc2p5d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc2p5d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc3d.rst b/doc/source/modules/orbit.space_charge.sc3d.rst new file mode 100644 index 00000000..35c82bf1 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc3d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc3d package +================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc3d.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc3d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc3d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.teapot.rst b/doc/source/modules/orbit.teapot.rst new file mode 100644 index 00000000..f924de25 --- /dev/null +++ b/doc/source/modules/orbit.teapot.rst @@ -0,0 +1,25 @@ +orbit.teapot package +==================== + +Submodules +---------- + + +.. automodule:: orbit.teapot.teapot + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.teapot.teapot_matrix_lattice + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.teapot + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.teapot_base.rst b/doc/source/modules/orbit.teapot_base.rst new file mode 100644 index 00000000..97eed985 --- /dev/null +++ b/doc/source/modules/orbit.teapot_base.rst @@ -0,0 +1,10 @@ +orbit.teapot\_base package +========================== + +Module contents +--------------- + +.. automodule:: orbit.teapot_base + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.time_dep.rst b/doc/source/modules/orbit.time_dep.rst new file mode 100644 index 00000000..88c59ecb --- /dev/null +++ b/doc/source/modules/orbit.time_dep.rst @@ -0,0 +1,25 @@ +orbit.time\_dep package +======================= + +Submodules +---------- + + +.. automodule:: orbit.time_dep.time_dep + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.time_dep.waveform + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.time_dep + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.fitting.rst b/doc/source/modules/orbit.utils.fitting.rst new file mode 100644 index 00000000..f1cf43ac --- /dev/null +++ b/doc/source/modules/orbit.utils.fitting.rst @@ -0,0 +1,49 @@ +orbit.utils.fitting package +=========================== + +Submodules +---------- + + +.. automodule:: orbit.utils.fitting.BisectionSearch1D + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.GoldenSectionSearch1D + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.PolynomialFit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.RandomSearch + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.SimplexSearch + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.Solver_lib + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.fitting + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst new file mode 100644 index 00000000..9ac256d8 --- /dev/null +++ b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst @@ -0,0 +1,37 @@ +orbit.utils.orbit\_mpi\_utils package +===================================== + +Submodules +---------- + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit_nHarm + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit_nHarm + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.orbit_mpi_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.rst b/doc/source/modules/orbit.utils.rst new file mode 100644 index 00000000..968b26d9 --- /dev/null +++ b/doc/source/modules/orbit.utils.rst @@ -0,0 +1,65 @@ +orbit.utils package +=================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.utils.fitting + orbit.utils.orbit_mpi_utils + orbit.utils.xml + +Submodules +---------- + + +.. automodule:: orbit.utils.NamedObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.ParamsDictObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.TypedObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.consts + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.multiDimArray + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbitFinalize + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.phaseOperations + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.xml.rst b/doc/source/modules/orbit.utils.xml.rst new file mode 100644 index 00000000..f1ceb913 --- /dev/null +++ b/doc/source/modules/orbit.utils.xml.rst @@ -0,0 +1,19 @@ +orbit.utils.xml package +======================= + +Submodules +---------- + + +.. automodule:: orbit.utils.xml.XmlDataAdaptor + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.xml + :members: + :show-inheritance: + :undoc-members: From c00785919d8cdf7c053e5996707dd9307954115a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 16 Dec 2025 12:39:59 -0500 Subject: [PATCH 03/25] autosummary working. Mostly. --- .gitignore | 1 + doc/source/conf.py | 6 +- doc/source/index.rst | 57 ++---- doc/source/install.rst | 193 ++++++++++++++++++ doc/source/{modules/orbit.rst => modules.rst} | 23 +-- doc/source/modules/orbit.aperture.rst | 31 --- doc/source/modules/orbit.bumps.rst | 31 --- doc/source/modules/orbit.bunch_generators.rst | 19 -- doc/source/modules/orbit.bunch_utils.rst | 25 --- doc/source/modules/orbit.collimation.rst | 25 --- doc/source/modules/orbit.core.rst | 10 - doc/source/modules/orbit.diagnostics.rst | 37 ---- doc/source/modules/orbit.errors.rst | 25 --- doc/source/modules/orbit.fieldtracker.rst | 25 --- doc/source/modules/orbit.foils.rst | 25 --- doc/source/modules/orbit.impedances.rst | 25 --- doc/source/modules/orbit.injection.rst | 43 ---- doc/source/modules/orbit.kickernodes.rst | 37 ---- doc/source/modules/orbit.lattice.rst | 37 ---- doc/source/modules/orbit.matching.rst | 19 -- doc/source/modules/orbit.matrix_lattice.rst | 25 --- doc/source/modules/orbit.orbit_correction.rst | 19 -- doc/source/modules/orbit.parsers.rst | 37 ---- doc/source/modules/orbit.py_linac.errors.rst | 19 -- doc/source/modules/orbit.py_linac.lattice.rst | 61 ------ .../orbit.py_linac.lattice_modifications.rst | 49 ----- .../modules/orbit.py_linac.linac_parsers.rst | 25 --- .../modules/orbit.py_linac.materials.rst | 19 -- .../orbit.py_linac.orbit_correction.rst | 19 -- .../orbit.py_linac.overlapping_fields.rst | 31 --- .../orbit.py_linac.rf_field_readers.rst | 25 --- doc/source/modules/orbit.py_linac.rst | 25 --- doc/source/modules/orbit.rf_cavities.rst | 25 --- .../orbit.space_charge.directforce2p5d.rst | 25 --- doc/source/modules/orbit.space_charge.rst | 43 ---- .../modules/orbit.space_charge.sc1d.rst | 25 --- .../orbit.space_charge.sc2dslicebyslice.rst | 25 --- .../modules/orbit.space_charge.sc2p5d.rst | 25 --- .../modules/orbit.space_charge.sc3d.rst | 25 --- doc/source/modules/orbit.teapot.rst | 25 --- doc/source/modules/orbit.teapot_base.rst | 10 - doc/source/modules/orbit.time_dep.rst | 25 --- doc/source/modules/orbit.utils.fitting.rst | 49 ----- .../modules/orbit.utils.orbit_mpi_utils.rst | 37 ---- doc/source/modules/orbit.utils.rst | 65 ------ doc/source/modules/orbit.utils.xml.rst | 19 -- 46 files changed, 218 insertions(+), 1253 deletions(-) create mode 100644 doc/source/install.rst rename doc/source/{modules/orbit.rst => modules.rst} (73%) delete mode 100644 doc/source/modules/orbit.aperture.rst delete mode 100644 doc/source/modules/orbit.bumps.rst delete mode 100644 doc/source/modules/orbit.bunch_generators.rst delete mode 100644 doc/source/modules/orbit.bunch_utils.rst delete mode 100644 doc/source/modules/orbit.collimation.rst delete mode 100644 doc/source/modules/orbit.core.rst delete mode 100644 doc/source/modules/orbit.diagnostics.rst delete mode 100644 doc/source/modules/orbit.errors.rst delete mode 100644 doc/source/modules/orbit.fieldtracker.rst delete mode 100644 doc/source/modules/orbit.foils.rst delete mode 100644 doc/source/modules/orbit.impedances.rst delete mode 100644 doc/source/modules/orbit.injection.rst delete mode 100644 doc/source/modules/orbit.kickernodes.rst delete mode 100644 doc/source/modules/orbit.lattice.rst delete mode 100644 doc/source/modules/orbit.matching.rst delete mode 100644 doc/source/modules/orbit.matrix_lattice.rst delete mode 100644 doc/source/modules/orbit.orbit_correction.rst delete mode 100644 doc/source/modules/orbit.parsers.rst delete mode 100644 doc/source/modules/orbit.py_linac.errors.rst delete mode 100644 doc/source/modules/orbit.py_linac.lattice.rst delete mode 100644 doc/source/modules/orbit.py_linac.lattice_modifications.rst delete mode 100644 doc/source/modules/orbit.py_linac.linac_parsers.rst delete mode 100644 doc/source/modules/orbit.py_linac.materials.rst delete mode 100644 doc/source/modules/orbit.py_linac.orbit_correction.rst delete mode 100644 doc/source/modules/orbit.py_linac.overlapping_fields.rst delete mode 100644 doc/source/modules/orbit.py_linac.rf_field_readers.rst delete mode 100644 doc/source/modules/orbit.py_linac.rst delete mode 100644 doc/source/modules/orbit.rf_cavities.rst delete mode 100644 doc/source/modules/orbit.space_charge.directforce2p5d.rst delete mode 100644 doc/source/modules/orbit.space_charge.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc1d.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc2p5d.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc3d.rst delete mode 100644 doc/source/modules/orbit.teapot.rst delete mode 100644 doc/source/modules/orbit.teapot_base.rst delete mode 100644 doc/source/modules/orbit.time_dep.rst delete mode 100644 doc/source/modules/orbit.utils.fitting.rst delete mode 100644 doc/source/modules/orbit.utils.orbit_mpi_utils.rst delete mode 100644 doc/source/modules/orbit.utils.rst delete mode 100644 doc/source/modules/orbit.utils.xml.rst diff --git a/.gitignore b/.gitignore index 44b61695..cddf9522 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ PyORBIT.egg-info .*.swp .eggs .venv +_autosummary/ diff --git a/doc/source/conf.py b/doc/source/conf.py index 12246764..ee878d1c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,8 +21,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] -autosummary_generate = True napoleon_numpy_docstring = True +autosummary_imported_members = True templates_path = ['_templates'] exclude_patterns = [] @@ -30,9 +30,9 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'furo' +html_theme = 'pydata_sphinx_theme' html_static_path = ['_static'] html_show_source_link = True html_theme_options = { - # 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', + 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', } diff --git a/doc/source/index.rst b/doc/source/index.rst index d16735f7..08e066b4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,54 +3,23 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -PyORBIT3 documentation -====================== +PyORBIT3 +======== -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + install .. toctree:: :maxdepth: 2 :caption: Modules - :hidden: - modules/orbit.aperture - modules/orbit.bump - modules/orbit.bunch_generators - modules/orbit.bunch_utils - modules/orbit.collimation - modules/orbit.diagnostics - modules/orbit.errors - modules/orbit.fieldtracker - modules/orbit.foils - modules/orbit.impedances - modules/orbit.injection - modules/orbit.kickernodes - modules/orbit.lattice - modules/orbit.matching - modules/orbit.matrix_lattice - modules/orbit.orbit_correction - modules/orbit.parsers - modules/orbit.py_linac.errors - modules/orbit.py_linac.lattice - modules/orbit.py_linac.lattice_modifications - modules/orbit.py_linac.linac_parsers - modules/orbit.py_linac.materials - modules/orbit.py_linac.orbit_correction - modules/orbit.py_linac.overlapping_fields - modules/orbit.py_linac.rf_field_readers - modules/orbit.py_linac - modules/orbit.rf_cavities - modules/orbit.space_charge.directforce2p5d - modules/orbit.space_charge - modules/orbit.space_charge.sc1d - modules/orbit.space_charge.sc2dslicebyslice - modules/orbit.space_charge.sc2p5d - modules/orbit.space_charge.sc3d - modules/orbit.teapot - modules/orbit.teapot_base - modules/orbit.time_dep - modules/orbit.utils.fitting - modules/orbit.utils.orbit_mpi_utils + modules + +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 00000000..a8978c20 --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,193 @@ +Installation +============================= + +1. Introduction +--------------- + +This guide provides instructions how to install PyORBIT code. This guide +doesn’t cover MPI enabled installation. The following configurations are +included in CI testing, versions will change as the runner images +progress. + ++------------+-----------+------------+-------+-----------+-----------+ +| HW | Arc | OS | P | Compiler | Package | +| | hitecture | | ython | | | ++============+===========+============+=======+===========+===========+ +| PC | x86_64 | CentOS | 3 | g | pip-24.0 | +| | | latest | .9.18 | cc-11.4.1 | | ++------------+-----------+------------+-------+-----------+-----------+ +| PC | x86_64 | Ubuntu | 3 | g | pip-24.0 | +| | | latest | .12.3 | cc-13.2.0 | | ++------------+-----------+------------+-------+-----------+-----------+ +| Apple | arm64 | macOS 14 | 3 | cla | pip-24.0 | +| Silicon | | | .12.3 | ng-15.0.0 | | ++------------+-----------+------------+-------+-----------+-----------+ +| PC | x86_64 | Ubuntu | 3. | g | con | +| | | latest | 10.14 | cc-13.2.0 | da-24.5.0 | ++------------+-----------+------------+-------+-----------+-----------+ + +2. Installation from source +--------------------------- + +First step is to clone the source code: + +.. code:: bash + + git clone https://github.com/PyORBIT-Collaboration/PyORBIT3.git + +Pip Setup +~~~~~~~~~ + +**PIP** based setup is more involved, we recommend using **conda** if +unsure. #### Prepare OS The following commands may require root access. + +.. raw:: html + +
+ +.. raw:: html + + + +Click for Ubuntu-based distributions + +.. raw:: html + + + +.. code:: bash + + apt-get update + apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + + + +Click for Redhat-based distributions + +.. raw:: html + + + +.. code:: bash + + dnf group install -y "Development Tools" + dnf install -y python3-devel fftw3-devel + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + + + +Click for Mac + +.. raw:: html + + + +Install Homebrew, make sure that homebrew programs are in the **$PATH** +(optional step in Homebrew installation) +``bash brew install pkg-config fftw`` + +.. raw:: html + +
+ +#### Create Python virtual environment Make sure that you have the +correct python version installed. We require python>3.9. Create virtual +environment. +``python3 -m venv .po3 . .po3/bin/activate pip install -U pip pip install -r requirements.txt pip install -U setuptools`` + +Conda Setup +~~~~~~~~~~~ + +First of all make sure you have conda installed and development +packages. Development packages for Ubuntu: + +:: + + apt update -y + apt install -y curl gpg git build-essential + +Then run the following: + +.. code:: bash + + cd pyorbit3 + conda env create -n po3 --file environment.yml + conda activate po3 + pip install -U meson-python setuptools setuptools-scm + +3. Build +-------- + +If you plan to modify PyORBIT’s code, install it in editable mode. You +will NOT need to rebuild after modifications to the code. +`Meson `__ will rebuild as necessary on import. + +:: + + pip install --no-build-isolation --editable . + +Alternatively if you don’t plan to modify PyORBIT’s code + +:: + + pip install . + +4. Run full SNS linac example +----------------------------- + +Navigate to your **examples** directory and launch tracking of SNS +linac. + +.. code:: bash + + cd examples/SNS_Linac/pyorbit3_linac_model/ + python pyorbit3_sns_linac_mebt_hebt2.py + +5. MPI consideration +-------------------- + +By default, the build system will try to find MPI and compile against +it. You can control which MPI to use with command line option when +building. + +.. code:: bash + + pip install --config-settings=setup-args="-DUSE_MPI=none" . + +Above will build PyORBIT without MPI even if MPI is present. You can +change that option to ``mpich``, ``ompi``, ``none`` or ``auto`` +(default). \| MPI flavor \| Installation command \| \|—————\|————–\| \| +No MPI \| +``pip install --config-settings=setup-args="-DUSE_MPI=none" .`` \| \| +The first found MPI installation if any \| +``pip install --config-settings=setup-args="-DUSE_MPI=auto" .`` \| \| +OpenMPI \| +``pip install --config-settings=setup-args="-DUSE_MPI=ompi" .`` \| \| +MPICH \| +``pip install --config-settings=setup-args="-DUSE_MPI=mpich" .`` \| + +Meson uses PKG_CONFIG to discover packages. It could be useful to help +it to find your MPI installation: + +.. code:: bash + + PKG_CONFIG_PATH=/opt/lib/pkgconfig pip install --verbose . diff --git a/doc/source/modules/orbit.rst b/doc/source/modules.rst similarity index 73% rename from doc/source/modules/orbit.rst rename to doc/source/modules.rst index baa4ca2e..1251b4e0 100644 --- a/doc/source/modules/orbit.rst +++ b/doc/source/modules.rst @@ -1,11 +1,12 @@ -orbit package -============= - -Subpackages ------------ - +Modules +======= .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :caption: Modules + +.. autosummary:: + :toctree: _autosummary + :recursive: orbit.aperture orbit.bumps @@ -32,11 +33,3 @@ Subpackages orbit.teapot_base orbit.time_dep orbit.utils - -Module contents ---------------- - -.. automodule:: orbit - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.aperture.rst b/doc/source/modules/orbit.aperture.rst deleted file mode 100644 index 9cf8d713..00000000 --- a/doc/source/modules/orbit.aperture.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.aperture package -====================== - -Submodules ----------- - - -.. automodule:: orbit.aperture.ApertureLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.aperture.ApertureLatticeRangeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.aperture.TeapotApertureNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.aperture - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bumps.rst b/doc/source/modules/orbit.bumps.rst deleted file mode 100644 index 639b975e..00000000 --- a/doc/source/modules/orbit.bumps.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.bumps package -=================== - -Submodules ----------- - - -.. automodule:: orbit.bumps.BumpLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bumps.TeapotBumpNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bumps.bumps - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bumps - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bunch_generators.rst b/doc/source/modules/orbit.bunch_generators.rst deleted file mode 100644 index d2aae682..00000000 --- a/doc/source/modules/orbit.bunch_generators.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.bunch\_generators package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.bunch_generators.distribution_generators - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bunch_generators - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bunch_utils.rst b/doc/source/modules/orbit.bunch_utils.rst deleted file mode 100644 index 35d80b35..00000000 --- a/doc/source/modules/orbit.bunch_utils.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.bunch\_utils package -========================== - -Submodules ----------- - - -.. automodule:: orbit.bunch_utils.particleidnumber - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bunch_utils.serialize - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bunch_utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.collimation.rst b/doc/source/modules/orbit.collimation.rst deleted file mode 100644 index b6100fdb..00000000 --- a/doc/source/modules/orbit.collimation.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.collimation package -========================= - -Submodules ----------- - - -.. automodule:: orbit.collimation.TeapotCollimatorNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.collimation.collimationLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.collimation - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.core.rst b/doc/source/modules/orbit.core.rst deleted file mode 100644 index 53921b7d..00000000 --- a/doc/source/modules/orbit.core.rst +++ /dev/null @@ -1,10 +0,0 @@ -orbit.core package -================== - -Module contents ---------------- - -.. automodule:: orbit.core - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.diagnostics.rst b/doc/source/modules/orbit.diagnostics.rst deleted file mode 100644 index 454b5406..00000000 --- a/doc/source/modules/orbit.diagnostics.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.diagnostics package -========================= - -Submodules ----------- - - -.. automodule:: orbit.diagnostics.TeapotDiagnosticsNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.diagnostics - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.diagnosticsLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.profiles - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.diagnostics - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.errors.rst b/doc/source/modules/orbit.errors.rst deleted file mode 100644 index 8ff1deb7..00000000 --- a/doc/source/modules/orbit.errors.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.errors package -==================== - -Submodules ----------- - - -.. automodule:: orbit.errors.ErrorLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.errors.ErrorNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.errors - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.fieldtracker.rst b/doc/source/modules/orbit.fieldtracker.rst deleted file mode 100644 index bba5190f..00000000 --- a/doc/source/modules/orbit.fieldtracker.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.fieldtracker package -========================== - -Submodules ----------- - - -.. automodule:: orbit.fieldtracker.TeapotFieldLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.fieldtracker.TeapotFieldTrackerNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.fieldtracker - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.foils.rst b/doc/source/modules/orbit.foils.rst deleted file mode 100644 index 6d1c11b4..00000000 --- a/doc/source/modules/orbit.foils.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.foils package -=================== - -Submodules ----------- - - -.. automodule:: orbit.foils.TeapotFoilNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.foils.foilLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.foils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.impedances.rst b/doc/source/modules/orbit.impedances.rst deleted file mode 100644 index 4c540fb2..00000000 --- a/doc/source/modules/orbit.impedances.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.impedances package -======================== - -Submodules ----------- - - -.. automodule:: orbit.impedances.ImpedanceLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.impedances.ImpedanceNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.impedances - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.injection.rst b/doc/source/modules/orbit.injection.rst deleted file mode 100644 index f5b4963e..00000000 --- a/doc/source/modules/orbit.injection.rst +++ /dev/null @@ -1,43 +0,0 @@ -orbit.injection package -======================= - -Submodules ----------- - - -.. automodule:: orbit.injection.InjectionLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.TeapotInjectionNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.distributions - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.injectparticles - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.joho - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.injection - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.kickernodes.rst b/doc/source/modules/orbit.kickernodes.rst deleted file mode 100644 index 2b000f0b..00000000 --- a/doc/source/modules/orbit.kickernodes.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.kickernodes package -========================= - -Submodules ----------- - - -.. automodule:: orbit.kickernodes.KickerLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.TeapotKickerNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.kicker - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.waveforms - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.kickernodes - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.lattice.rst b/doc/source/modules/orbit.lattice.rst deleted file mode 100644 index 68ed9568..00000000 --- a/doc/source/modules/orbit.lattice.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.lattice package -===================== - -Submodules ----------- - - -.. automodule:: orbit.lattice.AccActionsContainer - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccLattice - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccNodeBunchTracker - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.matching.rst b/doc/source/modules/orbit.matching.rst deleted file mode 100644 index 020f4937..00000000 --- a/doc/source/modules/orbit.matching.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.matching package -====================== - -Submodules ----------- - - -.. automodule:: orbit.matching.matching - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.matching - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.matrix_lattice.rst b/doc/source/modules/orbit.matrix_lattice.rst deleted file mode 100644 index b88fc3c4..00000000 --- a/doc/source/modules/orbit.matrix_lattice.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.matrix\_lattice package -============================= - -Submodules ----------- - - -.. automodule:: orbit.matrix_lattice.BaseMATRIX - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.matrix_lattice.MATRIX_Lattice - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.matrix_lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.orbit_correction.rst b/doc/source/modules/orbit.orbit_correction.rst deleted file mode 100644 index 87d458d1..00000000 --- a/doc/source/modules/orbit.orbit_correction.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.orbit\_correction package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.orbit_correction.orbit_correction - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.orbit_correction - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.parsers.rst b/doc/source/modules/orbit.parsers.rst deleted file mode 100644 index 8fffb512..00000000 --- a/doc/source/modules/orbit.parsers.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.parsers package -===================== - -Submodules ----------- - - -.. automodule:: orbit.parsers.field_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.mad_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.madx_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.sad_parser - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.parsers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.errors.rst b/doc/source/modules/orbit.py_linac.errors.rst deleted file mode 100644 index 304668e5..00000000 --- a/doc/source/modules/orbit.py_linac.errors.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.errors package -============================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.errors.ErrorNodesAndControllersLib - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.errors - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice.rst b/doc/source/modules/orbit.py_linac.lattice.rst deleted file mode 100644 index 08f273fb..00000000 --- a/doc/source/modules/orbit.py_linac.lattice.rst +++ /dev/null @@ -1,61 +0,0 @@ -orbit.py\_linac.lattice package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.lattice.LinacAccLatticeFunc - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacAccLatticeLib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacApertureNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacDiagnosticsNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacFieldOverlappingNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacRfGapNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacTransportMatrixGenNodes - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice_modifications.rst b/doc/source/modules/orbit.py_linac.lattice_modifications.rst deleted file mode 100644 index a04b7547..00000000 --- a/doc/source/modules/orbit.py_linac.lattice_modifications.rst +++ /dev/null @@ -1,49 +0,0 @@ -orbit.py\_linac.lattice\_modifications package -============================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.lattice_modifications.apertures_additions_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.errors_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.quad_overlap_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.rf_models_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.rf_quad_overlap_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.sns_aperture_additions - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.lattice_modifications - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.linac_parsers.rst b/doc/source/modules/orbit.py_linac.linac_parsers.rst deleted file mode 100644 index 32e83a62..00000000 --- a/doc/source/modules/orbit.py_linac.linac_parsers.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac.linac\_parsers package -====================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.linac_parsers.jparc_linac_lattice_factory - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.linac_parsers.sns_linac_lattice_factory - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.linac_parsers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.materials.rst b/doc/source/modules/orbit.py_linac.materials.rst deleted file mode 100644 index f777efb7..00000000 --- a/doc/source/modules/orbit.py_linac.materials.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.materials package -================================= - -Submodules ----------- - - -.. automodule:: orbit.py_linac.materials.VacuumWindowLinacNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.materials - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.orbit_correction.rst b/doc/source/modules/orbit.py_linac.orbit_correction.rst deleted file mode 100644 index 1ef126e2..00000000 --- a/doc/source/modules/orbit.py_linac.orbit_correction.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.orbit\_correction package -========================================= - -Submodules ----------- - - -.. automodule:: orbit.py_linac.orbit_correction.transport_lines_orbit_correction - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.orbit_correction - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.overlapping_fields.rst b/doc/source/modules/orbit.py_linac.overlapping_fields.rst deleted file mode 100644 index 9792294c..00000000 --- a/doc/source/modules/orbit.py_linac.overlapping_fields.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.py\_linac.overlapping\_fields package -=========================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.overlapping_fields.jparc_enge_func_factory - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.overlapping_fields.overlapping_quad_fields_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.overlapping_fields.sns_enge_func_factory - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.overlapping_fields - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rf_field_readers.rst b/doc/source/modules/orbit.py_linac.rf_field_readers.rst deleted file mode 100644 index 1e48280c..00000000 --- a/doc/source/modules/orbit.py_linac.rf_field_readers.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac.rf\_field\_readers package -========================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.rf_field_readers.RF_AxisFieldAnalysis - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.rf_field_readers.SuperFish_3D_RF_FieldReader - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.rf_field_readers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rst b/doc/source/modules/orbit.py_linac.rst deleted file mode 100644 index 2678c9f4..00000000 --- a/doc/source/modules/orbit.py_linac.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac package -======================= - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.py_linac.errors - orbit.py_linac.lattice - orbit.py_linac.lattice_modifications - orbit.py_linac.linac_parsers - orbit.py_linac.materials - orbit.py_linac.orbit_correction - orbit.py_linac.overlapping_fields - orbit.py_linac.rf_field_readers - -Module contents ---------------- - -.. automodule:: orbit.py_linac - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.rf_cavities.rst b/doc/source/modules/orbit.rf_cavities.rst deleted file mode 100644 index c41364a8..00000000 --- a/doc/source/modules/orbit.rf_cavities.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.rf\_cavities package -========================== - -Submodules ----------- - - -.. automodule:: orbit.rf_cavities.RFLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.rf_cavities.RFNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.rf_cavities - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.directforce2p5d.rst b/doc/source/modules/orbit.space_charge.directforce2p5d.rst deleted file mode 100644 index fd68e4b0..00000000 --- a/doc/source/modules/orbit.space_charge.directforce2p5d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.directforce2p5d package -=========================================== - -Submodules ----------- - - -.. automodule:: orbit.space_charge.directforce2p5d.directforceAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.directforce2p5d.directforceLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.directforce2p5d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.rst b/doc/source/modules/orbit.space_charge.rst deleted file mode 100644 index 1e6c9931..00000000 --- a/doc/source/modules/orbit.space_charge.rst +++ /dev/null @@ -1,43 +0,0 @@ -orbit.space\_charge package -=========================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.space_charge.directforce2p5d - orbit.space_charge.sc1d - orbit.space_charge.sc2dslicebyslice - orbit.space_charge.sc2p5d - orbit.space_charge.sc3d - -Submodules ----------- - - -.. automodule:: orbit.space_charge.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sccenteredLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc1d.rst b/doc/source/modules/orbit.space_charge.sc1d.rst deleted file mode 100644 index fc98d94d..00000000 --- a/doc/source/modules/orbit.space_charge.sc1d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc1d package -================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc1d.sc1DNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc1d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc1d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst deleted file mode 100644 index b20b40a6..00000000 --- a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc2dslicebyslice package -============================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc2dslicebyslice.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc2dslicebyslice.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc2dslicebyslice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2p5d.rst b/doc/source/modules/orbit.space_charge.sc2p5d.rst deleted file mode 100644 index 50c704d3..00000000 --- a/doc/source/modules/orbit.space_charge.sc2p5d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc2p5d package -================================== - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc2p5d.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc2p5d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc2p5d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc3d.rst b/doc/source/modules/orbit.space_charge.sc3d.rst deleted file mode 100644 index 35c82bf1..00000000 --- a/doc/source/modules/orbit.space_charge.sc3d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc3d package -================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc3d.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc3d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc3d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.teapot.rst b/doc/source/modules/orbit.teapot.rst deleted file mode 100644 index f924de25..00000000 --- a/doc/source/modules/orbit.teapot.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.teapot package -==================== - -Submodules ----------- - - -.. automodule:: orbit.teapot.teapot - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.teapot.teapot_matrix_lattice - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.teapot - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.teapot_base.rst b/doc/source/modules/orbit.teapot_base.rst deleted file mode 100644 index 97eed985..00000000 --- a/doc/source/modules/orbit.teapot_base.rst +++ /dev/null @@ -1,10 +0,0 @@ -orbit.teapot\_base package -========================== - -Module contents ---------------- - -.. automodule:: orbit.teapot_base - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.time_dep.rst b/doc/source/modules/orbit.time_dep.rst deleted file mode 100644 index 88c59ecb..00000000 --- a/doc/source/modules/orbit.time_dep.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.time\_dep package -======================= - -Submodules ----------- - - -.. automodule:: orbit.time_dep.time_dep - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.time_dep.waveform - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.time_dep - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.fitting.rst b/doc/source/modules/orbit.utils.fitting.rst deleted file mode 100644 index f1cf43ac..00000000 --- a/doc/source/modules/orbit.utils.fitting.rst +++ /dev/null @@ -1,49 +0,0 @@ -orbit.utils.fitting package -=========================== - -Submodules ----------- - - -.. automodule:: orbit.utils.fitting.BisectionSearch1D - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.GoldenSectionSearch1D - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.PolynomialFit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.RandomSearch - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.SimplexSearch - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.Solver_lib - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.fitting - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst deleted file mode 100644 index 9ac256d8..00000000 --- a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.utils.orbit\_mpi\_utils package -===================================== - -Submodules ----------- - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit_nHarm - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit_nHarm - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.orbit_mpi_utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.rst b/doc/source/modules/orbit.utils.rst deleted file mode 100644 index 968b26d9..00000000 --- a/doc/source/modules/orbit.utils.rst +++ /dev/null @@ -1,65 +0,0 @@ -orbit.utils package -=================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.utils.fitting - orbit.utils.orbit_mpi_utils - orbit.utils.xml - -Submodules ----------- - - -.. automodule:: orbit.utils.NamedObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.ParamsDictObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.TypedObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.consts - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.multiDimArray - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbitFinalize - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.phaseOperations - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.xml.rst b/doc/source/modules/orbit.utils.xml.rst deleted file mode 100644 index f1ceb913..00000000 --- a/doc/source/modules/orbit.utils.xml.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.utils.xml package -======================= - -Submodules ----------- - - -.. automodule:: orbit.utils.xml.XmlDataAdaptor - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.xml - :members: - :show-inheritance: - :undoc-members: From 76d5949c26c6fbf0c0751b01020cfb7ed7573b0a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 18 Dec 2025 15:34:36 -0500 Subject: [PATCH 04/25] Doxygen + breathe + exhale --- doc/.gitignore | 2 ++ doc/Makefile | 6 +++++- doc/source/conf.py | 30 +++++++++++++++++++++++++++++- doc/source/index.rst | 6 ++++++ 4 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..ca5796cb --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +_doxygen +source/api diff --git a/doc/Makefile b/doc/Makefile index d0c3cbf1..dc706e6c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,9 +12,13 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile clean # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index ee878d1c..22a6cd8c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -20,13 +20,41 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] +extensions = ['sphinx.ext.coverage', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.napoleon', + 'breathe', + 'exhale'] napoleon_numpy_docstring = True autosummary_imported_members = True templates_path = ['_templates'] exclude_patterns = [] +# -- Breathe and Exhale Options --------------------------------------------------------- +breathe_projects = { + "PyORBIT3": "./_doxygen/xml", + } +breathe_default_project = "PyORBIT3" + +doxyfile = '\n'.join([ + "INPUT = ../../src", + "EXCLUDE_PATTERNS = *wrap*", + ]) + +exhale_args = { + "containmentFolder": "./api", + "rootFileName": "pyorbit_root.rst", + "doxygenStripFromPath": "..", + "rootFileTitle": "PyORBIT3 API", + "createTreeView": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": doxyfile, + } + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/doc/source/index.rst b/doc/source/index.rst index 08e066b4..5c29b916 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,6 +18,12 @@ PyORBIT3 modules +.. toctree:: + :maxdepth: 2 + :caption: C++ Interface + + api/pyorbit_root.rst + Indices and tables ================== * :ref:`genindex` From 6084ddb5978c3f6a94f946898561022f26d0f66a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 18 Dec 2025 15:36:40 -0500 Subject: [PATCH 05/25] Should be api not _api --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index dc706e6c..16b56424 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 91da60132bcf8fee0edb413c7c69f45eefdbecc6 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 8 Jan 2026 17:10:42 -0500 Subject: [PATCH 06/25] Remove duplicates in C++ docs Resolved an issue where some of the C++ side of PyORBIT was getting documented twice. Ignored some macros that were causing errors while building documentation. Documentated a couple of methods as examples. --- doc/Makefile | 2 +- doc/source/conf.py | 10 +- doc/source/index.rst | 2 +- doc/source/modules.rst | 11 +- docs-environment.yml | 139 ++++++++++++++++++ src/mpi/orbit_mpi.cc | 2 + .../BunchDiagnostics/BunchTwissAnalysis.cc | 4 - .../BunchDiagnostics/BunchTwissAnalysis.hh | 11 +- src/orbit/MaterialInteractions/numrecipes.cc | 9 +- src/orbit/MaterialInteractions/numrecipes.hh | 49 +++++- .../UniformEllipsoidFieldCalculator.cc | 2 + src/utils/Random.cc | 2 + 12 files changed, 229 insertions(+), 14 deletions(-) create mode 100644 docs-environment.yml diff --git a/doc/Makefile b/doc/Makefile index 16b56424..e5bfb095 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api "$(SOURCEDIR)"/_autosummary @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index 22a6cd8c..1a9dc3d4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -5,6 +5,7 @@ # -- Path setup -------------------------------------------------------------- import sys +import pathlib from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) @@ -42,14 +43,16 @@ doxyfile = '\n'.join([ "INPUT = ../../src", - "EXCLUDE_PATTERNS = *wrap*", + "EXCLUDE_PATTERNS = *wrap* *_init.cc", + "PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS", + "PREDEFINED += PyObject_HEAD=\"PyObject ob_base;\"" ]) exhale_args = { "containmentFolder": "./api", "rootFileName": "pyorbit_root.rst", "doxygenStripFromPath": "..", - "rootFileTitle": "PyORBIT3 API", + "rootFileTitle": "PyORBIT3 C++ API", "createTreeView": True, "exhaleExecutesDoxygen": True, "exhaleDoxygenStdin": doxyfile, @@ -63,4 +66,7 @@ html_show_source_link = True html_theme_options = { 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', + 'logo': { + 'text': "PyORBIT3", + } } diff --git a/doc/source/index.rst b/doc/source/index.rst index 5c29b916..7d38cecb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -20,7 +20,7 @@ PyORBIT3 .. toctree:: :maxdepth: 2 - :caption: C++ Interface + :caption: C++ API api/pyorbit_root.rst diff --git a/doc/source/modules.rst b/doc/source/modules.rst index 1251b4e0..d8cb2ccd 100644 --- a/doc/source/modules.rst +++ b/doc/source/modules.rst @@ -5,7 +5,7 @@ Modules :caption: Modules .. autosummary:: - :toctree: _autosummary + :toctree: _autosummary/ :recursive: orbit.aperture @@ -26,7 +26,14 @@ Modules orbit.matrix_lattice orbit.orbit_correction orbit.parsers - orbit.py_linac + orbit.py_linac.errors + orbit.py_linac.lattice + orbit.py_linac.lattice_modifications + orbit.py_linac.linac_parsers + orbit.py_linac.materials + orbit.py_linac.orbit_correction + orbit.py_linac.overlapping_fields + orbit.py_linac.rf_field_readers orbit.rf_cavities orbit.space_charge orbit.teapot diff --git a/docs-environment.yml b/docs-environment.yml new file mode 100644 index 00000000..79a24a96 --- /dev/null +++ b/docs-environment.yml @@ -0,0 +1,139 @@ +name: docs +channels: + - conda-forge +dependencies: + - _openmp_mutex=4.5=7_kmp_llvm + - accessible-pygments=0.0.5=pyhd8ed1ab_1 + - alabaster=0.7.16=pyhd8ed1ab_0 + - babel=2.17.0=pyhd8ed1ab_0 + - backports.zstd=1.2.0=py313hf42fe89_0 + - beautifulsoup4=4.14.3=pyha770c72_0 + - black=25.12.0=pyh866005b_0 + - breathe=4.35.0=pyhd8ed1ab_4 + - brotli=1.2.0=h7d5ae5b_1 + - brotli-bin=1.2.0=hc919400_1 + - brotli-python=1.2.0=py313hde1f3bb_1 + - bzip2=1.0.8=hd037594_8 + - c-ares=1.34.6=hc919400_0 + - ca-certificates=2025.11.12=hbd8a1cb_0 + - certifi=2025.11.12=pyhd8ed1ab_0 + - charset-normalizer=3.4.4=pyhd8ed1ab_0 + - click=8.3.1=pyh8f84b5b_1 + - colorama=0.4.6=pyhd8ed1ab_1 + - contourpy=1.3.3=py313ha61f8ec_3 + - cycler=0.12.1=pyhcf101f3_2 + - docutils=0.17.1=py313h8f79df9_7 + - doxygen=1.13.2=h493aca8_0 + - exhale=0.3.7=pyhd8ed1ab_1 + - fonttools=4.61.1=pyh7db6752_0 + - freetype=2.14.1=hce30654_0 + - h2=4.3.0=pyhcf101f3_0 + - hpack=4.1.0=pyhd8ed1ab_0 + - hyperframe=6.1.0=pyhd8ed1ab_0 + - icu=75.1=hfee45f7_0 + - idna=3.11=pyhd8ed1ab_0 + - imagesize=1.4.1=pyhd8ed1ab_0 + - importlib-metadata=8.7.0=pyhe01879c_1 + - isort=7.0.0=pyhd8ed1ab_0 + - jinja2=3.1.6=pyhcf101f3_1 + - kiwisolver=1.4.9=py313h7add70c_2 + - lcms2=2.17=h7eeda09_0 + - lerc=4.0.0=hd64df32_1 + - libabseil=20250512.1=cxx17_hd41c47c_0 + - libblas=3.11.0=5_h51639a9_openblas + - libbrotlicommon=1.2.0=hc919400_1 + - libbrotlidec=1.2.0=hc919400_1 + - libbrotlienc=1.2.0=hc919400_1 + - libcblas=3.11.0=5_hb0561ab_openblas + - libcxx=21.1.8=hf598326_0 + - libdeflate=1.25=hc11a715_0 + - libev=4.33=h93a5062_2 + - libevent=2.1.12=h2757513_1 + - libexpat=2.7.3=haf25636_0 + - libfabric=2.4.0=hce30654_0 + - libfabric1=2.4.0=hc919400_0 + - libffi=3.5.2=he5f378a_0 + - libfreetype=2.14.1=hce30654_0 + - libfreetype6=2.14.1=h6da58f4_0 + - libgcc=15.2.0=hcbb3090_16 + - libgfortran=15.2.0=h07b0088_16 + - libgfortran5=15.2.0=hdae7583_16 + - libhwloc=2.12.1=default_ha3cc4f2_1003 + - libiconv=1.18=h23cfdf5_2 + - libjpeg-turbo=3.1.2=hc919400_0 + - liblapack=3.11.0=5_hd9741b5_openblas + - liblzma=5.8.1=h39f12f2_2 + - libmpdec=4.0.0=h5505292_0 + - libnghttp2=1.67.0=hc438710_0 + - libopenblas=0.3.30=openmp_ha158390_3 + - libpmix=5.0.8=h3e7ebac_2 + - libpng=1.6.53=hfab5511_0 + - libsqlite=3.51.1=h9a5124b_0 + - libtiff=4.7.1=h4030677_1 + - libuv=1.51.0=h6caf38d_1 + - libwebp-base=1.6.0=h07db88b_0 + - libxcb=1.17.0=hdb1d25a_0 + - libxml2=2.15.1=h9329255_0 + - libxml2-16=2.15.1=h0ff4647_0 + - libxslt=1.1.43=hb2570ba_1 + - libzlib=1.3.1=h8359307_2 + - llvm-openmp=21.1.8=h4a912ad_0 + - lxml=6.0.2=py313he6cafaa_2 + - markupsafe=3.0.3=pyh7db6752_0 + - matplotlib=3.10.8=py313h39782a4_0 + - matplotlib-base=3.10.8=py313h58042b9_0 + - mpi=1.0.1=openmpi + - munkres=1.1.4=pyhd8ed1ab_1 + - mypy_extensions=1.1.0=pyha770c72_0 + - ncurses=6.5=h5e97a16_3 + - nodeenv=1.9.1=pyhd8ed1ab_1 + - nodejs=25.2.1=h5230ea7_1 + - numpy=2.3.5=py313h9771d21_0 + - openjpeg=2.5.4=hbfb3c88_0 + - openmpi=5.0.8=h13a75e3_109 + - openssl=3.6.0=h5503f6c_0 + - packaging=25.0=pyh29332c3_1 + - pathspec=0.12.1=pyhd8ed1ab_1 + - pillow=12.0.0=py313ha86496b_2 + - pip=25.3=pyh145f28c_0 + - platformdirs=4.5.1=pyhcf101f3_0 + - pthread-stubs=0.4=hd74edd7_1002 + - pydata-sphinx-theme=0.13.3=pyhd8ed1ab_0 + - pygments=2.19.2=pyhd8ed1ab_0 + - pyparsing=3.2.5=pyhcf101f3_0 + - pyright=1.1.407=py313h9734d34_0 + - pysocks=1.7.1=pyha55dd90_7 + - python=3.13.11=hfc2f54d_100_cp313 + - python-dateutil=2.9.0.post0=pyhe01879c_2 + - python_abi=3.13=8_cp313 + - pytokens=0.3.0=pyhcf101f3_0 + - pytz=2025.2=pyhd8ed1ab_0 + - qhull=2020.2=h420ef59_5 + - readline=8.3=h46df422_0 + - requests=2.32.5=pyhd8ed1ab_0 + - roman-numerals=4.1.0=pyhd8ed1ab_0 + - scipy=1.16.3=py313h0d10b07_1 + - setuptools=80.9.0=pyhff2d567_0 + - six=1.17.0=pyhe01879c_1 + - snowballstemmer=3.0.1=pyhd8ed1ab_0 + - soupsieve=2.8=pyhd8ed1ab_0 + - sphinx=4.5.0=pyh6c4a22f_0 + - sphinxcontrib-applehelp=1.0.4=pyhd8ed1ab_0 + - sphinxcontrib-devhelp=1.0.2=py_0 + - sphinxcontrib-htmlhelp=2.0.1=pyhd8ed1ab_0 + - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_1 + - sphinxcontrib-qthelp=1.0.3=py_0 + - sphinxcontrib-serializinghtml=1.1.5=pyhd8ed1ab_2 + - standard-imghdr=3.13.0=pyh29332c3_0 + - tk=8.6.13=h892fb3f_3 + - tornado=6.5.4=py313h6535dbc_0 + - typing-extensions=4.15.0=h396c80c_0 + - typing_extensions=4.15.0=pyhcf101f3_0 + - tzdata=2025c=h8577fbf_0 + - unicodedata2=17.0.0=py313h6535dbc_1 + - urllib3=2.6.2=pyhd8ed1ab_0 + - xorg-libxau=1.0.12=hc919400_1 + - xorg-libxdmcp=1.1.5=hc919400_1 + - zipp=3.23.0=pyhcf101f3_1 + - zlib-ng=2.3.2=h248ca61_0 + - zstd=1.5.7=hbf9d68e_6 diff --git a/src/mpi/orbit_mpi.cc b/src/mpi/orbit_mpi.cc index 8a36065e..2dc97e71 100644 --- a/src/mpi/orbit_mpi.cc +++ b/src/mpi/orbit_mpi.cc @@ -5,6 +5,7 @@ #include #include +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) /** A C wrapper around MPI_Init. */ int ORBIT_MPI_Init(){ int res = 0; @@ -620,3 +621,4 @@ int ORBIT_MPI_Get_count(MPI_Status *status, MPI_Datatype datatype, int *count){ #endif return res; } +#endif // !defined(DOXYGEN_SHOULD_SKIP_THIS) diff --git a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc index 2063b6ae..0a361326 100644 --- a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc +++ b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc @@ -337,10 +337,6 @@ void BunchTwissAnalysis::computeBunchMoments(Bunch* bunch, int order, int disper } - - - -/** Returns the centered correlation <(x-)*(y-)> = - * */ double BunchTwissAnalysis::getCorrelation(int ic, int jc){ if(ic < 0 || ic > 5 || jc < 0 || jc >5) return 0.; return (corr_arr[ic+6*jc] - avg_arr[ic]* avg_arr[jc]); diff --git a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh index df6e2b4b..deaa20ee 100644 --- a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh +++ b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh @@ -26,7 +26,16 @@ class BunchTwissAnalysis: public OrbitUtils::CppPyWrapper /** Performs the Twiss analysis of the bunch */ void analyzeBunch(Bunch* bunch); - /** Returns the centered correlation <(x-)*(y-)> = - * */ + /** + * @brief Returns the centered correlation between two components. + * + * \f$\langle (x-\langle x\rangle)(y-\langle y\rangle)\rangle + * = \langle x y\rangle - \langle x\rangle\langle y\rangle\f$ + * + * @param ic Index of the first component (x). + * @param jc Index of the second component (y). + * @return The centered correlation value as a double. + */ double getCorrelation(int ic, int jc); /** Returns the average value for coordinate with index ic */ diff --git a/src/orbit/MaterialInteractions/numrecipes.cc b/src/orbit/MaterialInteractions/numrecipes.cc index eadd37ee..a38dd327 100644 --- a/src/orbit/MaterialInteractions/numrecipes.cc +++ b/src/orbit/MaterialInteractions/numrecipes.cc @@ -29,9 +29,8 @@ namespace OrbitUtils{ return sin(x)*exp(-fac1*pow(2*p*sin(x/2), 2))/pow(sin(x/2),4); } - int zbrak(float (*fx)(float, float, float, float), float x1, float x2, - int n, float xb1[], float xb2[], int &nb, float param1, + int n, float *xb1, float *xb2, int &nb, float param1, float param2, float param3) { int nbb, i; @@ -54,7 +53,9 @@ namespace OrbitUtils{ } #undef JMAX +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define JMAX 40 +#endif float rtbis(float (*func)(float, float, float, float), float x1, float x2, float xacc, float param1, float param2, float param3) @@ -134,8 +135,10 @@ namespace OrbitUtils{ #undef EPS #undef JMAX +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define EPS 1.0e-6 #define JMAX 20 +#endif float qsimp(float (*func)(float, float, float), float a, float b, float p, float fac1) @@ -164,7 +167,9 @@ namespace OrbitUtils{ /* note #undef's at end of file */ +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define FUNC(x, p, fac1) ((*rfunc)(x, p, fac1)) +#endif float trapzd(float (*rfunc)(float, float, float), float a, float b, int n, float p, float fac1) diff --git a/src/orbit/MaterialInteractions/numrecipes.hh b/src/orbit/MaterialInteractions/numrecipes.hh index 25f884e0..8059db80 100644 --- a/src/orbit/MaterialInteractions/numrecipes.hh +++ b/src/orbit/MaterialInteractions/numrecipes.hh @@ -16,7 +16,54 @@ namespace OrbitUtils{ float fstep(float s, float r_o, float pr_o, float theta); float rfunc(float x, float p, float fac1); - int zbrak(float (*fx)(float, float, float, float), float x1, float x2, int n, float xb1[], float xb2[], int &nb, float param1, + + /** + * @brief Bracket subintervals where a function changes sign. + * + * Scans the interval [x1, x2] by dividing it into @p n equal subintervals + * and records subinterval endpoints where the function @p fx changes sign + * (i.e., a root is bracketed). + * + * The function @p fx must have the signature: + * float fx(float x, float p1, float p2, float p3); + * It is evaluated at the grid points x1, x1 + dx, x1 + 2*dx, ..., x2, + * where dx = (x2 - x1) / n. + * + * When an interval [xb1[k], xb2[k]] is found such that fx(xb1[k]) and + * fx(xb2[k]) have opposite signs (fc*fp <= 0), the endpoints are stored + * in the output arrays xb1 and xb2 at the same index k (1-based indexing + * is used internally; the caller should account for this). + * + * @param fx Pointer to the function to examine. Signature: + * float fx(float x, float param1, float param2, float param3). + * @param x1 Left end of the search interval. + * @param x2 Right end of the search interval. + * @param n Number of equal subintervals to split [x1, x2] into. + * @param xb1 Output array to receive left endpoints of bracketing subintervals. + * Must be large enough to hold up to the capacity indicated by the + * integer referenced by @p nb (see @p nb description). + * @param xb2 Output array to receive right endpoints of bracketing subintervals. + * Same required capacity as @p xb1. + * @param nb Reference to an integer indicating the maximum number of bracket + * intervals the caller can accept on input; on return this integer + * is set to the actual number of brackets found (nb <= original nb). + * @param param1 First user parameter passed through to @p fx. + * @param param2 Second user parameter passed through to @p fx. + * @param param3 Third user parameter passed through to @p fx. + * + * @return Returns 0 on completion. If the number of found brackets reaches the + * input capacity (nb), the function returns immediately with xb1/xb2 + * filled up to that capacity and nb set equal to that capacity. + * + * @note + * - The function uses sequential evaluations of @p fx and treats a zero or a + * sign change (fc*fp <= 0.0) as a bracket. Adjacent subintervals that both + * satisfy this condition will each be reported. + * - The implementation uses 1-based indexing internally when filling xb1/xb2. + * The caller should allocate arrays accordingly and interpret the filled + * entries consistent with the calling convention used in the surrounding code. + */ + int zbrak(float (*fx)(float, float, float, float), float x1, float x2, int n, float *xb1, float *xb2, int &nb, float param1, float param2, float param3); float rtbis(float (*func)(float, float, float, float), float x1, float x2, float xacc, float param1, float param2, float param3); float bessj0(float x); diff --git a/src/spacecharge/UniformEllipsoidFieldCalculator.cc b/src/spacecharge/UniformEllipsoidFieldCalculator.cc index 42fc6970..811eb52d 100644 --- a/src/spacecharge/UniformEllipsoidFieldCalculator.cc +++ b/src/spacecharge/UniformEllipsoidFieldCalculator.cc @@ -15,6 +15,7 @@ using namespace OrbitUtils; //macros for max and min +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #ifndef max #define max( a, b ) ( ((a) > (b)) ? (a) : (b) ) #endif @@ -22,6 +23,7 @@ using namespace OrbitUtils; #ifndef min #define min( a, b ) ( ((a) < (b)) ? (a) : (b) ) #endif +#endif /** Constructor. There is no parameters */ UniformEllipsoidFieldCalculator::UniformEllipsoidFieldCalculator(): CppPyWrapper(NULL) diff --git a/src/utils/Random.cc b/src/utils/Random.cc index c19bafca..4725232a 100644 --- a/src/utils/Random.cc +++ b/src/utils/Random.cc @@ -21,6 +21,7 @@ using namespace OrbitUtils; // By default the random generator is initialized using a random seed (current time) +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) std::mt19937 mt(time(0)); void Random::seed(int seed){ @@ -31,3 +32,4 @@ void Random::seed(int seed){ double Random::ran1(){ return ((double) mt() / (mt.max())); } +#endif From 9aa42951af54da96107ee320a14355a240b7d363 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 12 Jan 2026 14:35:44 -0500 Subject: [PATCH 07/25] Write a new workflow to automatically build and publish docs to GH Pages --- .github/workflows/docs.yml | 30 +++++-- doc/source/_static/.gitkeep | 0 doc/source/_templates/.gitkeep | 0 docs-environment.yml | 149 ++++----------------------------- 4 files changed, 38 insertions(+), 141 deletions(-) create mode 100644 doc/source/_static/.gitkeep create mode 100644 doc/source/_templates/.gitkeep diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ce5f24dc..6f80ac25 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,11 +2,12 @@ name: Deploy Documentation to Pages on: - # Runs on pushes targeting the default branch push: branches: ["main"] - # Allows you to run this workflow manually from the Actions tab + pull_request: + branches: ["main"] + workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages @@ -31,20 +32,37 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - - uses: conda-incubator/setup-miniconda@v2 + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3 with: activate-environment: po3 + channels: conda-forge,defaults + auto-update-conda: true environment-file: docs-environment.yml - - uses: ammaraskar/sphinx-action@master - with: - docs-folder: "doc/" + + - name: Install PyORBIT3 + shell: bash -l {0} + run: | + conda activate po3 + pip install --config-settings=setup-args="-DUSE_MPI='none'" . + + - name: Build Documentation + shell: bash -l {0} + run: | + conda activate po3 + cd doc + make html + # - name: Setup Pages # uses: actions/configure-pages@v5 + - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: # Upload entire repository path: './doc/build/html' + - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 diff --git a/doc/source/_static/.gitkeep b/doc/source/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/doc/source/_templates/.gitkeep b/doc/source/_templates/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs-environment.yml b/docs-environment.yml index 79a24a96..b0584afd 100644 --- a/docs-environment.yml +++ b/docs-environment.yml @@ -2,138 +2,17 @@ name: docs channels: - conda-forge dependencies: - - _openmp_mutex=4.5=7_kmp_llvm - - accessible-pygments=0.0.5=pyhd8ed1ab_1 - - alabaster=0.7.16=pyhd8ed1ab_0 - - babel=2.17.0=pyhd8ed1ab_0 - - backports.zstd=1.2.0=py313hf42fe89_0 - - beautifulsoup4=4.14.3=pyha770c72_0 - - black=25.12.0=pyh866005b_0 - - breathe=4.35.0=pyhd8ed1ab_4 - - brotli=1.2.0=h7d5ae5b_1 - - brotli-bin=1.2.0=hc919400_1 - - brotli-python=1.2.0=py313hde1f3bb_1 - - bzip2=1.0.8=hd037594_8 - - c-ares=1.34.6=hc919400_0 - - ca-certificates=2025.11.12=hbd8a1cb_0 - - certifi=2025.11.12=pyhd8ed1ab_0 - - charset-normalizer=3.4.4=pyhd8ed1ab_0 - - click=8.3.1=pyh8f84b5b_1 - - colorama=0.4.6=pyhd8ed1ab_1 - - contourpy=1.3.3=py313ha61f8ec_3 - - cycler=0.12.1=pyhcf101f3_2 - - docutils=0.17.1=py313h8f79df9_7 - - doxygen=1.13.2=h493aca8_0 - - exhale=0.3.7=pyhd8ed1ab_1 - - fonttools=4.61.1=pyh7db6752_0 - - freetype=2.14.1=hce30654_0 - - h2=4.3.0=pyhcf101f3_0 - - hpack=4.1.0=pyhd8ed1ab_0 - - hyperframe=6.1.0=pyhd8ed1ab_0 - - icu=75.1=hfee45f7_0 - - idna=3.11=pyhd8ed1ab_0 - - imagesize=1.4.1=pyhd8ed1ab_0 - - importlib-metadata=8.7.0=pyhe01879c_1 - - isort=7.0.0=pyhd8ed1ab_0 - - jinja2=3.1.6=pyhcf101f3_1 - - kiwisolver=1.4.9=py313h7add70c_2 - - lcms2=2.17=h7eeda09_0 - - lerc=4.0.0=hd64df32_1 - - libabseil=20250512.1=cxx17_hd41c47c_0 - - libblas=3.11.0=5_h51639a9_openblas - - libbrotlicommon=1.2.0=hc919400_1 - - libbrotlidec=1.2.0=hc919400_1 - - libbrotlienc=1.2.0=hc919400_1 - - libcblas=3.11.0=5_hb0561ab_openblas - - libcxx=21.1.8=hf598326_0 - - libdeflate=1.25=hc11a715_0 - - libev=4.33=h93a5062_2 - - libevent=2.1.12=h2757513_1 - - libexpat=2.7.3=haf25636_0 - - libfabric=2.4.0=hce30654_0 - - libfabric1=2.4.0=hc919400_0 - - libffi=3.5.2=he5f378a_0 - - libfreetype=2.14.1=hce30654_0 - - libfreetype6=2.14.1=h6da58f4_0 - - libgcc=15.2.0=hcbb3090_16 - - libgfortran=15.2.0=h07b0088_16 - - libgfortran5=15.2.0=hdae7583_16 - - libhwloc=2.12.1=default_ha3cc4f2_1003 - - libiconv=1.18=h23cfdf5_2 - - libjpeg-turbo=3.1.2=hc919400_0 - - liblapack=3.11.0=5_hd9741b5_openblas - - liblzma=5.8.1=h39f12f2_2 - - libmpdec=4.0.0=h5505292_0 - - libnghttp2=1.67.0=hc438710_0 - - libopenblas=0.3.30=openmp_ha158390_3 - - libpmix=5.0.8=h3e7ebac_2 - - libpng=1.6.53=hfab5511_0 - - libsqlite=3.51.1=h9a5124b_0 - - libtiff=4.7.1=h4030677_1 - - libuv=1.51.0=h6caf38d_1 - - libwebp-base=1.6.0=h07db88b_0 - - libxcb=1.17.0=hdb1d25a_0 - - libxml2=2.15.1=h9329255_0 - - libxml2-16=2.15.1=h0ff4647_0 - - libxslt=1.1.43=hb2570ba_1 - - libzlib=1.3.1=h8359307_2 - - llvm-openmp=21.1.8=h4a912ad_0 - - lxml=6.0.2=py313he6cafaa_2 - - markupsafe=3.0.3=pyh7db6752_0 - - matplotlib=3.10.8=py313h39782a4_0 - - matplotlib-base=3.10.8=py313h58042b9_0 - - mpi=1.0.1=openmpi - - munkres=1.1.4=pyhd8ed1ab_1 - - mypy_extensions=1.1.0=pyha770c72_0 - - ncurses=6.5=h5e97a16_3 - - nodeenv=1.9.1=pyhd8ed1ab_1 - - nodejs=25.2.1=h5230ea7_1 - - numpy=2.3.5=py313h9771d21_0 - - openjpeg=2.5.4=hbfb3c88_0 - - openmpi=5.0.8=h13a75e3_109 - - openssl=3.6.0=h5503f6c_0 - - packaging=25.0=pyh29332c3_1 - - pathspec=0.12.1=pyhd8ed1ab_1 - - pillow=12.0.0=py313ha86496b_2 - - pip=25.3=pyh145f28c_0 - - platformdirs=4.5.1=pyhcf101f3_0 - - pthread-stubs=0.4=hd74edd7_1002 - - pydata-sphinx-theme=0.13.3=pyhd8ed1ab_0 - - pygments=2.19.2=pyhd8ed1ab_0 - - pyparsing=3.2.5=pyhcf101f3_0 - - pyright=1.1.407=py313h9734d34_0 - - pysocks=1.7.1=pyha55dd90_7 - - python=3.13.11=hfc2f54d_100_cp313 - - python-dateutil=2.9.0.post0=pyhe01879c_2 - - python_abi=3.13=8_cp313 - - pytokens=0.3.0=pyhcf101f3_0 - - pytz=2025.2=pyhd8ed1ab_0 - - qhull=2020.2=h420ef59_5 - - readline=8.3=h46df422_0 - - requests=2.32.5=pyhd8ed1ab_0 - - roman-numerals=4.1.0=pyhd8ed1ab_0 - - scipy=1.16.3=py313h0d10b07_1 - - setuptools=80.9.0=pyhff2d567_0 - - six=1.17.0=pyhe01879c_1 - - snowballstemmer=3.0.1=pyhd8ed1ab_0 - - soupsieve=2.8=pyhd8ed1ab_0 - - sphinx=4.5.0=pyh6c4a22f_0 - - sphinxcontrib-applehelp=1.0.4=pyhd8ed1ab_0 - - sphinxcontrib-devhelp=1.0.2=py_0 - - sphinxcontrib-htmlhelp=2.0.1=pyhd8ed1ab_0 - - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_1 - - sphinxcontrib-qthelp=1.0.3=py_0 - - sphinxcontrib-serializinghtml=1.1.5=pyhd8ed1ab_2 - - standard-imghdr=3.13.0=pyh29332c3_0 - - tk=8.6.13=h892fb3f_3 - - tornado=6.5.4=py313h6535dbc_0 - - typing-extensions=4.15.0=h396c80c_0 - - typing_extensions=4.15.0=pyhcf101f3_0 - - tzdata=2025c=h8577fbf_0 - - unicodedata2=17.0.0=py313h6535dbc_1 - - urllib3=2.6.2=pyhd8ed1ab_0 - - xorg-libxau=1.0.12=hc919400_1 - - xorg-libxdmcp=1.1.5=hc919400_1 - - zipp=3.23.0=pyhcf101f3_1 - - zlib-ng=2.3.2=h248ca61_0 - - zstd=1.5.7=hbf9d68e_6 + - doxygen + - exhale + - pydata-sphinx-theme + - python=3.13 + - sphinx + - breathe + - standard-imghdr + - fftw + - numpy + - scipy + - matplotlib + - meson + - pkg-config + - ninja From cfa00830dc82587350e4140645c52186b57a6188 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 12 Jan 2026 16:35:52 -0500 Subject: [PATCH 08/25] Don't build docs on PR Building and re-deploying on each PR may be problematic as the github-pages environment is protected. --- .github/workflows/docs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6f80ac25..1d89d168 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,9 +5,6 @@ on: push: branches: ["main"] - pull_request: - branches: ["main"] - workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages From c66b2905a578183d8c217e5400a5b5e0f57d719a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 10:51:08 -0500 Subject: [PATCH 09/25] Add markdown support and 'copy' button on codeblocks --- README.md | 23 ++--- doc/source/conf.py | 3 + doc/source/index.rst | 2 +- doc/source/install.md | 1 + doc/source/install.rst | 193 ----------------------------------------- docs-environment.yml | 2 + 6 files changed, 20 insertions(+), 204 deletions(-) create mode 120000 doc/source/install.md delete mode 100644 doc/source/install.rst diff --git a/README.md b/README.md index 8e5b4277..b896f29f 100644 --- a/README.md +++ b/README.md @@ -29,16 +29,16 @@ The following commands may require root access.
Click for Ubuntu-based distributions - + ```bash apt-get update apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git - ``` + ```
Click for Redhat-based distributions - + ```bash dnf group install -y "Development Tools" dnf install -y python3-devel fftw3-devel @@ -47,16 +47,18 @@ The following commands may require root access.
Click for Mac - + Install Homebrew, make sure that homebrew programs are in the **$PATH** (optional step in Homebrew installation) + ```bash brew install pkg-config fftw ```
- + #### Create Python virtual environment Make sure that you have the correct python version installed. We require python>3.9.
Create virtual environment. + ``` python3 -m venv .po3 . .po3/bin/activate @@ -70,6 +72,7 @@ The following commands may require root access. First of all make sure you have conda installed and development packages.
Development packages for Ubuntu: + ``` apt update -y apt install -y curl gpg git build-essential @@ -87,18 +90,18 @@ pip install -U meson-python setuptools setuptools-scm ## 3. Build -If you plan to modify PyORBIT's code, install it in editable mode. +If you plan to modify PyORBIT's code, install it in editable mode. You will NOT need to rebuild after modifications to the code. [Meson](MesonBuild.md) will rebuild as necessary on import. ``` pip install --no-build-isolation --editable . ``` Alternatively if you don't plan to modify PyORBIT's code + ``` pip install . ``` - ## 4. Run full SNS linac example Navigate to your **examples** directory and launch tracking of SNS linac. @@ -116,9 +119,9 @@ pip install --config-settings=setup-args="-DUSE_MPI=none" . Above will build PyORBIT without MPI even if MPI is present. You can change that option to `mpich`, `ompi`, `none` or `auto` (default).
| MPI flavor | Installation command | |---------------|--------------| -| No MPI | `pip install --config-settings=setup-args="-DUSE_MPI=none" .` | -| The first found MPI installation if any | `pip install --config-settings=setup-args="-DUSE_MPI=auto" .` | -| OpenMPI | `pip install --config-settings=setup-args="-DUSE_MPI=ompi" .` | +| No MPI | `pip install --config-settings=setup-args="-DUSE_MPI=none" .` | +| The first found MPI installation if any | `pip install --config-settings=setup-args="-DUSE_MPI=auto" .` | +| OpenMPI | `pip install --config-settings=setup-args="-DUSE_MPI=ompi" .` | | MPICH | `pip install --config-settings=setup-args="-DUSE_MPI=mpich" .` | Meson uses PKG_CONFIG to discover packages. It could be useful to help it to find your MPI installation: diff --git a/doc/source/conf.py b/doc/source/conf.py index 1a9dc3d4..1a1dec2c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -27,8 +27,11 @@ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', + 'sphinx_copybutton', + 'myst_parser', 'breathe', 'exhale'] + napoleon_numpy_docstring = True autosummary_imported_members = True diff --git a/doc/source/index.rst b/doc/source/index.rst index 7d38cecb..0afbf680 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,7 +10,7 @@ PyORBIT3 :maxdepth: 2 :caption: Getting Started - install + install.md .. toctree:: :maxdepth: 2 diff --git a/doc/source/install.md b/doc/source/install.md new file mode 120000 index 00000000..fe840054 --- /dev/null +++ b/doc/source/install.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/doc/source/install.rst b/doc/source/install.rst deleted file mode 100644 index a8978c20..00000000 --- a/doc/source/install.rst +++ /dev/null @@ -1,193 +0,0 @@ -Installation -============================= - -1. Introduction ---------------- - -This guide provides instructions how to install PyORBIT code. This guide -doesn’t cover MPI enabled installation. The following configurations are -included in CI testing, versions will change as the runner images -progress. - -+------------+-----------+------------+-------+-----------+-----------+ -| HW | Arc | OS | P | Compiler | Package | -| | hitecture | | ython | | | -+============+===========+============+=======+===========+===========+ -| PC | x86_64 | CentOS | 3 | g | pip-24.0 | -| | | latest | .9.18 | cc-11.4.1 | | -+------------+-----------+------------+-------+-----------+-----------+ -| PC | x86_64 | Ubuntu | 3 | g | pip-24.0 | -| | | latest | .12.3 | cc-13.2.0 | | -+------------+-----------+------------+-------+-----------+-----------+ -| Apple | arm64 | macOS 14 | 3 | cla | pip-24.0 | -| Silicon | | | .12.3 | ng-15.0.0 | | -+------------+-----------+------------+-------+-----------+-----------+ -| PC | x86_64 | Ubuntu | 3. | g | con | -| | | latest | 10.14 | cc-13.2.0 | da-24.5.0 | -+------------+-----------+------------+-------+-----------+-----------+ - -2. Installation from source ---------------------------- - -First step is to clone the source code: - -.. code:: bash - - git clone https://github.com/PyORBIT-Collaboration/PyORBIT3.git - -Pip Setup -~~~~~~~~~ - -**PIP** based setup is more involved, we recommend using **conda** if -unsure. #### Prepare OS The following commands may require root access. - -.. raw:: html - -
- -.. raw:: html - - - -Click for Ubuntu-based distributions - -.. raw:: html - - - -.. code:: bash - - apt-get update - apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git - -.. raw:: html - -
- -.. raw:: html - -
- -.. raw:: html - - - -Click for Redhat-based distributions - -.. raw:: html - - - -.. code:: bash - - dnf group install -y "Development Tools" - dnf install -y python3-devel fftw3-devel - -.. raw:: html - -
- -.. raw:: html - -
- -.. raw:: html - - - -Click for Mac - -.. raw:: html - - - -Install Homebrew, make sure that homebrew programs are in the **$PATH** -(optional step in Homebrew installation) -``bash brew install pkg-config fftw`` - -.. raw:: html - -
- -#### Create Python virtual environment Make sure that you have the -correct python version installed. We require python>3.9. Create virtual -environment. -``python3 -m venv .po3 . .po3/bin/activate pip install -U pip pip install -r requirements.txt pip install -U setuptools`` - -Conda Setup -~~~~~~~~~~~ - -First of all make sure you have conda installed and development -packages. Development packages for Ubuntu: - -:: - - apt update -y - apt install -y curl gpg git build-essential - -Then run the following: - -.. code:: bash - - cd pyorbit3 - conda env create -n po3 --file environment.yml - conda activate po3 - pip install -U meson-python setuptools setuptools-scm - -3. Build --------- - -If you plan to modify PyORBIT’s code, install it in editable mode. You -will NOT need to rebuild after modifications to the code. -`Meson `__ will rebuild as necessary on import. - -:: - - pip install --no-build-isolation --editable . - -Alternatively if you don’t plan to modify PyORBIT’s code - -:: - - pip install . - -4. Run full SNS linac example ------------------------------ - -Navigate to your **examples** directory and launch tracking of SNS -linac. - -.. code:: bash - - cd examples/SNS_Linac/pyorbit3_linac_model/ - python pyorbit3_sns_linac_mebt_hebt2.py - -5. MPI consideration --------------------- - -By default, the build system will try to find MPI and compile against -it. You can control which MPI to use with command line option when -building. - -.. code:: bash - - pip install --config-settings=setup-args="-DUSE_MPI=none" . - -Above will build PyORBIT without MPI even if MPI is present. You can -change that option to ``mpich``, ``ompi``, ``none`` or ``auto`` -(default). \| MPI flavor \| Installation command \| \|—————\|————–\| \| -No MPI \| -``pip install --config-settings=setup-args="-DUSE_MPI=none" .`` \| \| -The first found MPI installation if any \| -``pip install --config-settings=setup-args="-DUSE_MPI=auto" .`` \| \| -OpenMPI \| -``pip install --config-settings=setup-args="-DUSE_MPI=ompi" .`` \| \| -MPICH \| -``pip install --config-settings=setup-args="-DUSE_MPI=mpich" .`` \| - -Meson uses PKG_CONFIG to discover packages. It could be useful to help -it to find your MPI installation: - -.. code:: bash - - PKG_CONFIG_PATH=/opt/lib/pkgconfig pip install --verbose . diff --git a/docs-environment.yml b/docs-environment.yml index b0584afd..f27037c3 100644 --- a/docs-environment.yml +++ b/docs-environment.yml @@ -7,6 +7,8 @@ dependencies: - pydata-sphinx-theme - python=3.13 - sphinx + - sphinx-copybutton + - myst-parser - breathe - standard-imghdr - fftw From 59ce106b07ce4132810ff26d2f2e041ba475f80f Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 10:53:35 -0500 Subject: [PATCH 10/25] formatting --- doc/source/conf.py | 79 ++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 1a1dec2c..8f0fd2f5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -5,7 +5,6 @@ # -- Path setup -------------------------------------------------------------- import sys -import pathlib from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) @@ -13,63 +12,67 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'PyORBIT3' -copyright = '2025, PyORBIT Collaboration' -author = 'PyORBIT Collaboration' -release = 'v3.0.1' +project = "PyORBIT3" +copyright = "2025, PyORBIT Collaboration" +author = "PyORBIT Collaboration" +release = "v3.0.1" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.coverage', - 'sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.napoleon', - 'sphinx_copybutton', - 'myst_parser', - 'breathe', - 'exhale'] +extensions = [ + "sphinx.ext.coverage", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx_copybutton", + "myst_parser", + "breathe", + "exhale", +] napoleon_numpy_docstring = True autosummary_imported_members = True -templates_path = ['_templates'] +templates_path = ["_templates"] exclude_patterns = [] # -- Breathe and Exhale Options --------------------------------------------------------- breathe_projects = { - "PyORBIT3": "./_doxygen/xml", - } + "PyORBIT3": "./_doxygen/xml", +} breathe_default_project = "PyORBIT3" -doxyfile = '\n'.join([ - "INPUT = ../../src", - "EXCLUDE_PATTERNS = *wrap* *_init.cc", - "PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS", - "PREDEFINED += PyObject_HEAD=\"PyObject ob_base;\"" - ]) +doxyfile = "\n".join( + [ + "INPUT = ../../src", + "EXCLUDE_PATTERNS = *wrap* *_init.cc", + "PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS", + 'PREDEFINED += PyObject_HEAD="PyObject ob_base;"', + ] +) exhale_args = { - "containmentFolder": "./api", - "rootFileName": "pyorbit_root.rst", - "doxygenStripFromPath": "..", - "rootFileTitle": "PyORBIT3 C++ API", - "createTreeView": True, - "exhaleExecutesDoxygen": True, - "exhaleDoxygenStdin": doxyfile, - } + "containmentFolder": "./api", + "rootFileName": "pyorbit_root.rst", + "doxygenStripFromPath": "..", + "rootFileTitle": "PyORBIT3 C++ API", + "createTreeView": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": doxyfile, +} # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'pydata_sphinx_theme' -html_static_path = ['_static'] +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] html_show_source_link = True html_theme_options = { - 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', - 'logo': { - 'text': "PyORBIT3", - } + "github_url": "https://github.com/PyORBIT-Collaboration/PyORBIT3", + "logo": { + "text": "PyORBIT3", + }, } From 40c83cc8f382c0b8d8c4662e5cc2f7425181ed23 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 10:59:57 -0500 Subject: [PATCH 11/25] remove comments --- .github/workflows/docs.yml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1d89d168..bc538460 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,3 @@ -# Simple workflow for deploying static content to GitHub Pages name: Deploy Documentation to Pages on: @@ -20,7 +19,6 @@ concurrency: cancel-in-progress: false jobs: - # Single deploy job since we're just deploying deploy: environment: name: github-pages @@ -41,6 +39,7 @@ jobs: - name: Install PyORBIT3 shell: bash -l {0} run: | + # @woodtp -- MPI isn't required to build docs and enabling it causes Sphinx to segfault. conda activate po3 pip install --config-settings=setup-args="-DUSE_MPI='none'" . @@ -51,13 +50,9 @@ jobs: cd doc make html - # - name: Setup Pages - # uses: actions/configure-pages@v5 - - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - # Upload entire repository path: './doc/build/html' - name: Deploy to GitHub Pages From bce103fbf1395b790a2c65ec6001d356b9e390a0 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 11:36:19 -0500 Subject: [PATCH 12/25] split into two jobs so that build and deploy can be re-run independently if necessary --- .github/workflows/docs.yml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bc538460..9ca1aca7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,10 +19,7 @@ concurrency: cancel-in-progress: false jobs: - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} + build: runs-on: ubuntu-latest steps: - name: Checkout @@ -55,6 +52,13 @@ jobs: with: path: './doc/build/html' + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 From 5f422a45c43d8f7dec34fb81d8ceb82be2ce46d3 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 12:12:56 -0500 Subject: [PATCH 13/25] Extend deploy job timeout to 1 hour If things are really busy, the default 10 minutes is an insufficient amount of time to wait in the queue. --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9ca1aca7..d8d65c8d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -62,3 +62,5 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 + with: + timeout: 3600000 From 0d6552e8b80c126dec46343d1917b3fdde19e7b9 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 14:18:03 -0500 Subject: [PATCH 14/25] Move doc building to a resuable workflow Now docs can be built on pull request without attempting to publish to Pages. --- .github/workflows/compilation.yml | 17 +++++++------ .github/workflows/docs-build.yml | 42 +++++++++++++++++++++++++++++++ .github/workflows/docs.yml | 34 +++---------------------- 3 files changed, 55 insertions(+), 38 deletions(-) create mode 100644 .github/workflows/docs-build.yml diff --git a/.github/workflows/compilation.yml b/.github/workflows/compilation.yml index c06d3621..c40130af 100644 --- a/.github/workflows/compilation.yml +++ b/.github/workflows/compilation.yml @@ -34,8 +34,8 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh - + .github/workflows/pip-versions.sh + centos-stream: runs-on: ubuntu-latest @@ -60,8 +60,8 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh - + .github/workflows/pip-versions.sh + ubuntu: @@ -88,7 +88,7 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh + .github/workflows/pip-versions.sh conda: @@ -120,7 +120,7 @@ jobs: - name: Print Versions run: | - .github/workflows/conda-versions.sh + .github/workflows/conda-versions.sh mpich: runs-on: ubuntu-latest @@ -145,4 +145,7 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh \ No newline at end of file + .github/workflows/pip-versions.sh + + build-docs: + uses: ./.github/workflows/docs-build.yml diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml new file mode 100644 index 00000000..7d49d10e --- /dev/null +++ b/.github/workflows/docs-build.yml @@ -0,0 +1,42 @@ +on: + workflow_call: + inputs: + upload-artifact: + required: false + type: boolean + default: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: po3 + channels: conda-forge,defaults + auto-update-conda: true + environment-file: docs-environment.yml + + - name: Install PyORBIT3 + shell: bash -l {0} + run: | + # @woodtp -- MPI isn't required to build docs and enabling it causes Sphinx to segfault. + conda activate po3 + pip install --config-settings=setup-args="-DUSE_MPI='none'" . + + - name: Build Documentation + shell: bash -l {0} + run: | + conda activate po3 + cd doc + make html + + - name: Upload artifact + if: ${{ inputs.upload-artifact }} + uses: actions/upload-pages-artifact@v3 + with: + path: './doc/build/html' diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d8d65c8d..679aee4e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,37 +20,9 @@ concurrency: jobs: build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Miniconda - uses: conda-incubator/setup-miniconda@v3 - with: - activate-environment: po3 - channels: conda-forge,defaults - auto-update-conda: true - environment-file: docs-environment.yml - - - name: Install PyORBIT3 - shell: bash -l {0} - run: | - # @woodtp -- MPI isn't required to build docs and enabling it causes Sphinx to segfault. - conda activate po3 - pip install --config-settings=setup-args="-DUSE_MPI='none'" . - - - name: Build Documentation - shell: bash -l {0} - run: | - conda activate po3 - cd doc - make html - - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: './doc/build/html' + uses: ./.github/workflows/docs-build.yml + with: + upload-artifact: true deploy: needs: build From cdc67ff4bd612ea62d3b7396b7ee867ad94a9834 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 14:51:18 -0500 Subject: [PATCH 15/25] this needs quotes ..? --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 679aee4e..67ae0d30 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,4 +35,4 @@ jobs: id: deployment uses: actions/deploy-pages@v4 with: - timeout: 3600000 + timeout: '3600000' From 433c3ff536931a9efbd1769dc7756a7efc0add02 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 15:13:10 -0500 Subject: [PATCH 16/25] Revert "this needs quotes ..?" This reverts commit cdc67ff4bd612ea62d3b7396b7ee867ad94a9834. --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 67ae0d30..679aee4e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,4 +35,4 @@ jobs: id: deployment uses: actions/deploy-pages@v4 with: - timeout: '3600000' + timeout: 3600000 From 0b356fb45a3c03d464920b29b03f297548034a84 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 15:13:18 -0500 Subject: [PATCH 17/25] Adjust workflow to deploy to pyorbit-collaboration/pyorbit-collaboration.github.io This reverts commit 5f422a45c43d8f7dec34fb81d8ceb82be2ce46d3. Deploy to pyorbit-collaboration/pyorbit-collaboration.github.io --- .github/workflows/docs.yml | 33 ++++++-- doc/source/conf.py | 6 +- doc/source/contributing.md | 118 ++++++++++++++++++++++++++ doc/source/home.md | 1 + doc/source/index.rst | 15 ++-- doc/source/install.md | 132 +++++++++++++++++++++++++++++- py/orbit/bunch_utils/serialize.py | 20 +---- 7 files changed, 288 insertions(+), 37 deletions(-) create mode 100644 doc/source/contributing.md create mode 100644 doc/source/home.md mode change 120000 => 100644 doc/source/install.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 679aee4e..f7b27d12 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -6,7 +6,6 @@ on: workflow_dispatch: -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: contents: read pages: write @@ -27,12 +26,28 @@ jobs: deploy: needs: build runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 - with: - timeout: 3600000 + - name: Download Artifact + uses: actions/download-artifact@v5 + with: + name: github-pages + - name: Extract artifact.tar in place + run: | + TARFILE=$(find . -type f -name "*.tar*" | head -n1) + if [ -z "$TARFILE" ]; then + echo "No tar archive found in workspace" + ls -la + exit 1 + fi + mkdir -p ./site + tar -xvf "$TARFILE" -C ./site + + - name: List extracted site + run: ls -R ./site + + - name: Deploy + uses: peaceiris/actions-gh-pages@v4 + with: + deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }} + external_repository: pyorbit-collaboration/pyorbit-collaboration.github.io + publish_dir: ./site diff --git a/doc/source/conf.py b/doc/source/conf.py index 8f0fd2f5..28f51606 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -58,7 +58,8 @@ "containmentFolder": "./api", "rootFileName": "pyorbit_root.rst", "doxygenStripFromPath": "..", - "rootFileTitle": "PyORBIT3 C++ API", + "rootFileTitle": "C++ API", + "fullApiSubSectionTitle": "", "createTreeView": True, "exhaleExecutesDoxygen": True, "exhaleDoxygenStdin": doxyfile, @@ -76,3 +77,6 @@ "text": "PyORBIT3", }, } +# html_sidebars = { +# "**": ["sidebar-nav-bs"] +# } diff --git a/doc/source/contributing.md b/doc/source/contributing.md new file mode 100644 index 00000000..90f41005 --- /dev/null +++ b/doc/source/contributing.md @@ -0,0 +1,118 @@ +# Contributor Guide + +## Building the Docs + +To build and preview the documentation locally, create a new Conda environment from the `docs-environment.yml` and activate it. +Then, `cd` into the `doc/` directory and run `make html`. + +```sh +conda env create -f docs-environment.yml -n docs +conda activate docs +cd doc +make html +``` + +You can view the documentation in your browser by opening `docs/build/html/index.html`. + +## Documenting Python Code + +### Where to add documentation + +Add or edit docstrings directly in the Python source files following the NumPy docstring style. +For generated API pages, autosummary will produce stub pages from the docstrings and signatures. +Any new top-level `orbit` submodule must be registered by adding it to `docs/source/modules.rst`. + +### Docstring format + +Use the [NumPy docstring convention](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard). +Keep short summary on the first line. +Use Parameters with a table-like list; include types and optional default values. + +```python +def foo(x, y=1): + """ + Short one-line summary. + + Longer description (optional), explaining behavior, side effects, and important details. + + .. math:: + + z = x \cdot y + + Parameters + ---------- + x : int + Description of x. + y : int, optional + Description of y. Defaults to 1. + + Returns + ------- + float + Description of the return value. + + Raises + ------ + ValueError + If x is negative. + + """ + ... +``` + +## Documenting C++ Code + +### Where to add documentation + +Add Doxygen comments directly in the C++ header or source files above the declarations. + +Example documenting a function: + +```cpp +/** + * @brief Compute a simple value. + * + * The relation is given by the LaTeX expression: \f\$ z = x \cdot y \f\$. + * Detailed description if needed. + * + * @param x First input. + * @param y Second input. + * @return Computed value. + * @throws std::invalid\_argument if x <= 0. + * + * Example: + * @code + * double r = foo(x, y); + * @endcode + */ +double foo(double x, double y); +``` + +Example documenting a class: + +```cpp +/** + * @class Bar + * @brief Represents a simple concept. + * + * More detailed class description. + * + * Mathematical note: \f\$E = mc^2\f\$ + */ +class Bar { +public: + /** Construct with a value. */ + Bar(double v); + /** Return the value. */ + double value() const; + // ... +}; +``` + +## For Maintainers + +The docs are deployed to the [main GitHub Pages repository for the PyORBIT Collaboration](https://github.com/pyorbit-collaboration/pyorbit-collaboration.github.io) +via an Action ([peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)) defined in [PyORBIT-Collaboration/PyORBIT3/.github/workflow/docs.yml](https://github.com/PyORBIT-Collaboration/PyORBIT3/blob/main/.github/workflows/docs.yml). +The action requires a [Deploy Key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys) to be added to the PyORBIT-Collaboration/PyORBIT-Collaboration.github.io repository +as well as a [Secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) to be created in the PyORBIT-Collaboration/PyORBIT3 repository. +Refer to the [instructions for deploying to an external repository](https://github.com/peaceiris/actions-gh-pages?tab=readme-ov-file#%EF%B8%8F-deploy-to-external-repository-external_repository) for more details. diff --git a/doc/source/home.md b/doc/source/home.md new file mode 100644 index 00000000..11a94892 --- /dev/null +++ b/doc/source/home.md @@ -0,0 +1 @@ +# PyORBIT3 diff --git a/doc/source/index.rst b/doc/source/index.rst index 0afbf680..78861088 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,27 +3,24 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -PyORBIT3 -======== +.. include:: ./home.md + :parser: myst_parser.sphinx_ .. toctree:: :maxdepth: 2 :caption: Getting Started - install.md + install + contributing .. toctree:: :maxdepth: 2 - :caption: Modules + :caption: API Reference modules - -.. toctree:: - :maxdepth: 2 - :caption: C++ API - api/pyorbit_root.rst + Indices and tables ================== * :ref:`genindex` diff --git a/doc/source/install.md b/doc/source/install.md deleted file mode 120000 index fe840054..00000000 --- a/doc/source/install.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md \ No newline at end of file diff --git a/doc/source/install.md b/doc/source/install.md new file mode 100644 index 00000000..07b07005 --- /dev/null +++ b/doc/source/install.md @@ -0,0 +1,131 @@ +# Installation Guide + +This guide provides instructions how to install PyORBIT code.
+This guide doesn't cover MPI enabled installation.
+The following configurations are included in CI testing, versions will change as the runner images progress. + +| HW | Architecture | OS | Python | Compiler | Package | +|---------------|--------------|---------------|---------|--------------|--------------| +| PC | x86_64 | CentOS latest | 3.9.18 | gcc-11.4.1 | pip-24.0 | +| PC | x86_64 | Ubuntu latest | 3.12.3 | gcc-13.2.0 | pip-24.0 | +| Apple Silicon | arm64 | macOS 14 | 3.12.3 | clang-15.0.0 | pip-24.0 | +| PC | x86_64 | Ubuntu latest | 3.10.14 | gcc-13.2.0 | conda-24.5.0 | + + + +## Installation from source + +First step is to clone the source code: + +```bash +git clone https://github.com/PyORBIT-Collaboration/PyORBIT3.git +``` + +### Pip Setup +**PIP** based setup is more involved, we recommend using **conda** if unsure. +#### Prepare OS +The following commands may require root access. + +
+ Click for Ubuntu-based distributions + + ```bash + apt-get update + apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git + ``` +
+ +
+ Click for Redhat-based distributions + + ```bash + dnf group install -y "Development Tools" + dnf install -y python3-devel fftw3-devel + ``` +
+ +
+ Click for Mac + + Install Homebrew, make sure that homebrew programs are in the **$PATH** (optional step in Homebrew installation) + + ```bash + brew install pkg-config fftw + ``` +
+ + #### Create Python virtual environment + Make sure that you have the correct python version installed. We require python>3.9.
+ Create virtual environment. + + ``` + python3 -m venv .po3 + . .po3/bin/activate + pip install -U pip + pip install -r requirements.txt + pip install -U setuptools + ``` + + +### Conda Setup + +First of all make sure you have conda installed and development packages.
+Development packages for Ubuntu: + +``` +apt update -y +apt install -y curl gpg git build-essential +``` + +Then run the following: + +```bash +cd pyorbit3 +conda env create -n po3 --file environment.yml +conda activate po3 +pip install -U meson-python setuptools setuptools-scm +``` + + +## Build + +If you plan to modify PyORBIT's code, install it in editable mode. +You will NOT need to rebuild after modifications to the code. [Meson](MesonBuild.md) will rebuild as necessary on import. +``` +pip install --no-build-isolation --editable . +``` + +Alternatively if you don't plan to modify PyORBIT's code + +``` +pip install . +``` + +## 4. Run full SNS linac example + +Navigate to your **examples** directory and launch tracking of SNS linac. + +```bash +cd examples/SNS_Linac/pyorbit3_linac_model/ +python pyorbit3_sns_linac_mebt_hebt2.py +``` + +## MPI consideration + +By default, the build system will try to find MPI and compile against it. You can control which MPI to use with command line option when building. +```bash +pip install --config-settings=setup-args="-DUSE_MPI=none" . +``` +Above will build PyORBIT without MPI even if MPI is present. You can change that option to `mpich`, `ompi`, `none` or `auto` (default).
+| MPI flavor | Installation command | +|---------------|--------------| +| No MPI | `pip install --config-settings=setup-args="-DUSE_MPI=none" .` | +| The first found MPI installation if any | `pip install --config-settings=setup-args="-DUSE_MPI=auto" .` | +| OpenMPI | `pip install --config-settings=setup-args="-DUSE_MPI=ompi" .` | +| MPICH | `pip install --config-settings=setup-args="-DUSE_MPI=mpich" .` | + +Meson uses PKG_CONFIG to discover packages. It could be useful to help it to find your MPI installation: + +```bash +PKG_CONFIG_PATH=/opt/lib/pkgconfig pip install --verbose . +``` diff --git a/py/orbit/bunch_utils/serialize.py b/py/orbit/bunch_utils/serialize.py index 1a8a0e3b..4e23a7d8 100644 --- a/py/orbit/bunch_utils/serialize.py +++ b/py/orbit/bunch_utils/serialize.py @@ -80,6 +80,7 @@ def collect_bunch( bunch: Bunch, output_dir: str | pathlib.Path = "/tmp", return_memmap: bool = True ) -> BunchDict | None: """Collects attributes from a PyOrbit Bunch across all MPI ranks and returns it as a dictionary. + Parameters ---------- bunch : Bunch @@ -91,27 +92,12 @@ def collect_bunch( return_memmap : bool, optional Return the bunch coordinates as a memory-mapped NumPy array, otherwise the entire array is copied into RAM and returned as normal NDArray. Default is True. + Returns ------- BunchDict | None A dictionary containing the collected bunch attributes. Returns None if not on the root MPI rank or if the global bunch size is 0. - BunchDict structure: - { - "coords": NDArray[np.float64] of shape (N, 6) where N is the total number of macroparticles, - and the 6 columns correspond to [x, xp, y, yp, z, dE] in units of [m, rad, m, rad, m, GeV], respectively. - "sync_part": { - "coords": NDArray[np.float64] of shape (3,), - "kin_energy": np.float64, - "momentum": np.float64, - "beta": np.float64, - "gamma": np.float64, - "time": np.float64 - }, - "attributes": { - : , - ... - } - } + Raises ------ FileNotFoundError From 9003bf6fc04c858bb1b47f2425b54b555d3513b0 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 15 Jan 2026 14:18:50 -0500 Subject: [PATCH 18/25] Split cpp and python autoapi into separate dirs, introduce automodapi and separate markdown files for each pyorbit module --- .gitignore | 2 + doc/Makefile | 2 +- doc/source/conf.py | 8 ++- doc/source/contributing.md | 30 ++++++++- doc/source/index.rst | 2 +- doc/source/modules.rst | 66 +++++++++----------- doc/source/modules/orbit.aperture.md | 6 ++ doc/source/modules/orbit.bumps.md | 6 ++ doc/source/modules/orbit.bunch_generators.md | 6 ++ doc/source/modules/orbit.bunch_utils.md | 6 ++ doc/source/modules/orbit.collimation.md | 6 ++ doc/source/modules/orbit.core.md | 6 ++ doc/source/modules/orbit.diagnostics.md | 6 ++ doc/source/modules/orbit.errors.md | 7 +++ doc/source/modules/orbit.fieldtracker.md | 7 +++ doc/source/modules/orbit.foils.md | 7 +++ doc/source/modules/orbit.impedances.md | 7 +++ doc/source/modules/orbit.injection.md | 7 +++ doc/source/modules/orbit.kickernodes.md | 7 +++ doc/source/modules/orbit.lattice.md | 7 +++ doc/source/modules/orbit.matching.md | 7 +++ doc/source/modules/orbit.matrix_lattice.md | 7 +++ doc/source/modules/orbit.orbit_correction.md | 7 +++ doc/source/modules/orbit.parsers.md | 7 +++ doc/source/modules/orbit.py_linac.md | 21 +++++++ doc/source/modules/orbit.rf_cavities.md | 7 +++ doc/source/modules/orbit.space_charge.md | 7 +++ doc/source/modules/orbit.teapot.md | 7 +++ doc/source/modules/orbit.teapot_base.md | 7 +++ doc/source/modules/orbit.time_dep.md | 7 +++ doc/source/modules/orbit.utils.md | 7 +++ 31 files changed, 251 insertions(+), 41 deletions(-) create mode 100644 doc/source/modules/orbit.aperture.md create mode 100644 doc/source/modules/orbit.bumps.md create mode 100644 doc/source/modules/orbit.bunch_generators.md create mode 100644 doc/source/modules/orbit.bunch_utils.md create mode 100644 doc/source/modules/orbit.collimation.md create mode 100644 doc/source/modules/orbit.core.md create mode 100644 doc/source/modules/orbit.diagnostics.md create mode 100644 doc/source/modules/orbit.errors.md create mode 100644 doc/source/modules/orbit.fieldtracker.md create mode 100644 doc/source/modules/orbit.foils.md create mode 100644 doc/source/modules/orbit.impedances.md create mode 100644 doc/source/modules/orbit.injection.md create mode 100644 doc/source/modules/orbit.kickernodes.md create mode 100644 doc/source/modules/orbit.lattice.md create mode 100644 doc/source/modules/orbit.matching.md create mode 100644 doc/source/modules/orbit.matrix_lattice.md create mode 100644 doc/source/modules/orbit.orbit_correction.md create mode 100644 doc/source/modules/orbit.parsers.md create mode 100644 doc/source/modules/orbit.py_linac.md create mode 100644 doc/source/modules/orbit.rf_cavities.md create mode 100644 doc/source/modules/orbit.space_charge.md create mode 100644 doc/source/modules/orbit.teapot.md create mode 100644 doc/source/modules/orbit.teapot_base.md create mode 100644 doc/source/modules/orbit.time_dep.md create mode 100644 doc/source/modules/orbit.utils.md diff --git a/.gitignore b/.gitignore index cddf9522..2f2b3deb 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,5 @@ PyORBIT.egg-info .eggs .venv _autosummary/ +_api/ +_cpp_api/ diff --git a/doc/Makefile b/doc/Makefile index e5bfb095..85f8baf5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api "$(SOURCEDIR)"/_autosummary + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api "$(SOURCEDIR)"/_cpp_api "$(SOURCEDIR)"/_autosummary @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index 28f51606..bf87c3c2 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -27,6 +27,9 @@ "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.napoleon", + "sphinx_autodoc_typehints", + "sphinx_automodapi.automodapi", + "sphinx_automodapi.smart_resolver", "sphinx_copybutton", "myst_parser", "breathe", @@ -36,6 +39,9 @@ napoleon_numpy_docstring = True autosummary_imported_members = True +numpydoc_show_class_members=False +automodapi_toctreedirnm = "_api" + templates_path = ["_templates"] exclude_patterns = [] @@ -55,7 +61,7 @@ ) exhale_args = { - "containmentFolder": "./api", + "containmentFolder": "./_cpp_api", "rootFileName": "pyorbit_root.rst", "doxygenStripFromPath": "..", "rootFileTitle": "C++ API", diff --git a/doc/source/contributing.md b/doc/source/contributing.md index 90f41005..110f6fdb 100644 --- a/doc/source/contributing.md +++ b/doc/source/contributing.md @@ -14,6 +14,34 @@ make html You can view the documentation in your browser by opening `docs/build/html/index.html`. +## Creating Static Pages + +Simple pages may be written in Markdown or [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) and stored in the `doc/source/` directory. +Markdown support is enabled via the MyST parser extension, refer to the [MyST syntax guide](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) +for more information related to composition of Markdown documents. +Add the file to a `toc` block in the `doc/source/index.rst` in order for it be included in the main documentation. + + +1. Create your document containing useful information under `doc/source/useful_info.md`. + +```md + + +# Useful Information +``` + +2. Add the file to a `toc` block in the `doc/source/index.rst`. + +```rst +.. toctree:: + + useful_info +``` + +:::{tip} +If you want to create a hierarchical structure of pages, add the subdirectory to the `doc/source/` directory and add the file to a `toc` block in the parent file. +::: + ## Documenting Python Code ### Where to add documentation @@ -115,4 +143,4 @@ The docs are deployed to the [main GitHub Pages repository for the PyORBIT Colla via an Action ([peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)) defined in [PyORBIT-Collaboration/PyORBIT3/.github/workflow/docs.yml](https://github.com/PyORBIT-Collaboration/PyORBIT3/blob/main/.github/workflows/docs.yml). The action requires a [Deploy Key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys) to be added to the PyORBIT-Collaboration/PyORBIT-Collaboration.github.io repository as well as a [Secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) to be created in the PyORBIT-Collaboration/PyORBIT3 repository. -Refer to the [instructions for deploying to an external repository](https://github.com/peaceiris/actions-gh-pages?tab=readme-ov-file#%EF%B8%8F-deploy-to-external-repository-external_repository) for more details. +Refer to the [instructions for deploying to an external repository](https://github.com/peaceiris/actions-gh-pages?tab=readme-ov-file#%EF%B8%8F-deploy-to-external-repository-external_repository) and [Create SSH Deploy Key](https://github.com/peaceiris/actions-gh-pages?tab=readme-ov-file#tips-and-faq) for more details. diff --git a/doc/source/index.rst b/doc/source/index.rst index 78861088..c2894f70 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,7 +18,7 @@ :caption: API Reference modules - api/pyorbit_root.rst + _cpp_api/pyorbit_root Indices and tables diff --git a/doc/source/modules.rst b/doc/source/modules.rst index d8cb2ccd..c4d0fd44 100644 --- a/doc/source/modules.rst +++ b/doc/source/modules.rst @@ -1,42 +1,34 @@ Modules ======= + +orbit.aperture +############## + .. toctree:: :maxdepth: 2 - :caption: Modules - -.. autosummary:: - :toctree: _autosummary/ - :recursive: - orbit.aperture - orbit.bumps - orbit.bunch_generators - orbit.bunch_utils - orbit.collimation - orbit.core - orbit.diagnostics - orbit.errors - orbit.fieldtracker - orbit.foils - orbit.impedances - orbit.injection - orbit.kickernodes - orbit.lattice - orbit.matching - orbit.matrix_lattice - orbit.orbit_correction - orbit.parsers - orbit.py_linac.errors - orbit.py_linac.lattice - orbit.py_linac.lattice_modifications - orbit.py_linac.linac_parsers - orbit.py_linac.materials - orbit.py_linac.orbit_correction - orbit.py_linac.overlapping_fields - orbit.py_linac.rf_field_readers - orbit.rf_cavities - orbit.space_charge - orbit.teapot - orbit.teapot_base - orbit.time_dep - orbit.utils + modules/orbit.aperture + modules/orbit.bumps + modules/orbit.bunch_generators + modules/orbit.bunch_utils + modules/orbit.collimation + modules/orbit.core + modules/orbit.diagnostics + modules/orbit.errors + modules/orbit.fieldtracker + modules/orbit.foils + modules/orbit.impedances + modules/orbit.injection + modules/orbit.kickernodes + modules/orbit.lattice + modules/orbit.matching + modules/orbit.matrix_lattice + modules/orbit.orbit_correction + modules/orbit.parsers + modules/orbit.py_linac + modules/orbit.rf_cavities + modules/orbit.space_charge + modules/orbit.teapot + modules/orbit.teapot_base + modules/orbit.time_dep + modules/orbit.utils diff --git a/doc/source/modules/orbit.aperture.md b/doc/source/modules/orbit.aperture.md new file mode 100644 index 00000000..7cdfeb25 --- /dev/null +++ b/doc/source/modules/orbit.aperture.md @@ -0,0 +1,6 @@ +# orbit.aperture + +```{eval-rst} +.. automodapi:: orbit.aperture + :no-heading: +``` diff --git a/doc/source/modules/orbit.bumps.md b/doc/source/modules/orbit.bumps.md new file mode 100644 index 00000000..9843c369 --- /dev/null +++ b/doc/source/modules/orbit.bumps.md @@ -0,0 +1,6 @@ +# orbit.bumps + +```{eval-rst} +.. automodapi:: orbit.bumps + :no-heading: +``` diff --git a/doc/source/modules/orbit.bunch_generators.md b/doc/source/modules/orbit.bunch_generators.md new file mode 100644 index 00000000..3cd509c1 --- /dev/null +++ b/doc/source/modules/orbit.bunch_generators.md @@ -0,0 +1,6 @@ +# orbit.bunch_generators + +```{eval-rst} +.. automodapi:: orbit.bunch_generators + :no-heading: +``` diff --git a/doc/source/modules/orbit.bunch_utils.md b/doc/source/modules/orbit.bunch_utils.md new file mode 100644 index 00000000..a13530fb --- /dev/null +++ b/doc/source/modules/orbit.bunch_utils.md @@ -0,0 +1,6 @@ +# orbit.bunch_utils + +```{eval-rst} +.. automodapi:: orbit.bunch_utils + :no-heading: +``` diff --git a/doc/source/modules/orbit.collimation.md b/doc/source/modules/orbit.collimation.md new file mode 100644 index 00000000..49e5aa3f --- /dev/null +++ b/doc/source/modules/orbit.collimation.md @@ -0,0 +1,6 @@ +# orbit.collimation + +```{eval-rst} +.. automodapi:: orbit.collimation + :no-heading: +``` diff --git a/doc/source/modules/orbit.core.md b/doc/source/modules/orbit.core.md new file mode 100644 index 00000000..6cc6c69b --- /dev/null +++ b/doc/source/modules/orbit.core.md @@ -0,0 +1,6 @@ +# orbit.core + +```{eval-rst} +.. automodapi:: orbit.core + :no-heading: +``` diff --git a/doc/source/modules/orbit.diagnostics.md b/doc/source/modules/orbit.diagnostics.md new file mode 100644 index 00000000..5de6a8d6 --- /dev/null +++ b/doc/source/modules/orbit.diagnostics.md @@ -0,0 +1,6 @@ +# orbit.diagnostics + +```{eval-rst} +.. automodapi:: orbit.diagnostics + :no-heading: +``` diff --git a/doc/source/modules/orbit.errors.md b/doc/source/modules/orbit.errors.md new file mode 100644 index 00000000..aa2e69ef --- /dev/null +++ b/doc/source/modules/orbit.errors.md @@ -0,0 +1,7 @@ +# orbit.errors + +```{eval-rst} +.. automodapi:: orbit.errors + :no-heading: +``` + diff --git a/doc/source/modules/orbit.fieldtracker.md b/doc/source/modules/orbit.fieldtracker.md new file mode 100644 index 00000000..b6e3bcdc --- /dev/null +++ b/doc/source/modules/orbit.fieldtracker.md @@ -0,0 +1,7 @@ +# orbit.fieldtracker + +```{eval-rst} +.. automodapi:: orbit.fieldtracker + :no-heading: +``` + diff --git a/doc/source/modules/orbit.foils.md b/doc/source/modules/orbit.foils.md new file mode 100644 index 00000000..184c14f9 --- /dev/null +++ b/doc/source/modules/orbit.foils.md @@ -0,0 +1,7 @@ +# orbit.foils + +```{eval-rst} +.. automodapi:: orbit.foils + :no-heading: +``` + diff --git a/doc/source/modules/orbit.impedances.md b/doc/source/modules/orbit.impedances.md new file mode 100644 index 00000000..570b8b1f --- /dev/null +++ b/doc/source/modules/orbit.impedances.md @@ -0,0 +1,7 @@ +# orbit.impedances + +```{eval-rst} +.. automodapi:: orbit.impedances + :no-heading: +``` + diff --git a/doc/source/modules/orbit.injection.md b/doc/source/modules/orbit.injection.md new file mode 100644 index 00000000..408659bb --- /dev/null +++ b/doc/source/modules/orbit.injection.md @@ -0,0 +1,7 @@ +# orbit.injection + +```{eval-rst} +.. automodapi:: orbit.injection + :no-heading: +``` + diff --git a/doc/source/modules/orbit.kickernodes.md b/doc/source/modules/orbit.kickernodes.md new file mode 100644 index 00000000..a4754587 --- /dev/null +++ b/doc/source/modules/orbit.kickernodes.md @@ -0,0 +1,7 @@ +# orbit.kickernodes + +```{eval-rst} +.. automodapi:: orbit.kickernodes + :no-heading: +``` + diff --git a/doc/source/modules/orbit.lattice.md b/doc/source/modules/orbit.lattice.md new file mode 100644 index 00000000..9964c15a --- /dev/null +++ b/doc/source/modules/orbit.lattice.md @@ -0,0 +1,7 @@ +# orbit.lattice + +```{eval-rst} +.. automodapi:: orbit.lattice + :no-heading: +``` + diff --git a/doc/source/modules/orbit.matching.md b/doc/source/modules/orbit.matching.md new file mode 100644 index 00000000..f62e1f87 --- /dev/null +++ b/doc/source/modules/orbit.matching.md @@ -0,0 +1,7 @@ +# orbit.matching + +```{eval-rst} +.. automodapi:: orbit.matching + :no-heading: +``` + diff --git a/doc/source/modules/orbit.matrix_lattice.md b/doc/source/modules/orbit.matrix_lattice.md new file mode 100644 index 00000000..c8e70bcb --- /dev/null +++ b/doc/source/modules/orbit.matrix_lattice.md @@ -0,0 +1,7 @@ +# orbit.matrix_lattice + +```{eval-rst} +.. automodapi:: orbit.matrix_lattice + :no-heading: +``` + diff --git a/doc/source/modules/orbit.orbit_correction.md b/doc/source/modules/orbit.orbit_correction.md new file mode 100644 index 00000000..0ddec622 --- /dev/null +++ b/doc/source/modules/orbit.orbit_correction.md @@ -0,0 +1,7 @@ +# orbit.orbit_correction + +```{eval-rst} +.. automodapi:: orbit.orbit_correction + :no-heading: +``` + diff --git a/doc/source/modules/orbit.parsers.md b/doc/source/modules/orbit.parsers.md new file mode 100644 index 00000000..ce8b06c0 --- /dev/null +++ b/doc/source/modules/orbit.parsers.md @@ -0,0 +1,7 @@ +# orbit.parsers + +```{eval-rst} +.. automodapi:: orbit.parsers + :no-heading: +``` + diff --git a/doc/source/modules/orbit.py_linac.md b/doc/source/modules/orbit.py_linac.md new file mode 100644 index 00000000..5e00cfb2 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.md @@ -0,0 +1,21 @@ +# orbit.py_linac + +```{eval-rst} +.. automodapi:: orbit.py_linac.errors + :no-heading: +.. automodapi:: orbit.py_linac.lattice + :no-heading: +.. automodapi:: orbit.py_linac.lattice_modifications + :no-heading: +.. automodapi:: orbit.py_linac.linac_parsers + :no-heading: +.. automodapi:: orbit.py_linac.materials + :no-heading: +.. automodapi:: orbit.py_linac.orbit_correction + :no-heading: +.. automodapi:: orbit.py_linac.overlapping_fields + :no-heading: +.. automodapi:: orbit.py_linac.rf_field_readers + :no-heading: +``` + diff --git a/doc/source/modules/orbit.rf_cavities.md b/doc/source/modules/orbit.rf_cavities.md new file mode 100644 index 00000000..64bd5f4e --- /dev/null +++ b/doc/source/modules/orbit.rf_cavities.md @@ -0,0 +1,7 @@ +# orbit.rf_cavities + +```{eval-rst} +.. automodapi:: orbit.rf_cavities + :no-heading: +``` + diff --git a/doc/source/modules/orbit.space_charge.md b/doc/source/modules/orbit.space_charge.md new file mode 100644 index 00000000..6d8c1049 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.md @@ -0,0 +1,7 @@ +# orbit.space_charge + +```{eval-rst} +.. automodapi:: orbit.space_charge + :no-heading: +``` + diff --git a/doc/source/modules/orbit.teapot.md b/doc/source/modules/orbit.teapot.md new file mode 100644 index 00000000..ebe31a31 --- /dev/null +++ b/doc/source/modules/orbit.teapot.md @@ -0,0 +1,7 @@ +# orbit.teapot + +```{eval-rst} +.. automodapi:: orbit.teapot + :no-heading: +``` + diff --git a/doc/source/modules/orbit.teapot_base.md b/doc/source/modules/orbit.teapot_base.md new file mode 100644 index 00000000..b69030ad --- /dev/null +++ b/doc/source/modules/orbit.teapot_base.md @@ -0,0 +1,7 @@ +# orbit.teapot_base + +```{eval-rst} +.. automodapi:: orbit.teapot_base + :no-heading: +``` + diff --git a/doc/source/modules/orbit.time_dep.md b/doc/source/modules/orbit.time_dep.md new file mode 100644 index 00000000..da5972eb --- /dev/null +++ b/doc/source/modules/orbit.time_dep.md @@ -0,0 +1,7 @@ +# orbit.time_dep + +```{eval-rst} +.. automodapi:: orbit.time_dep + :no-heading: +``` + diff --git a/doc/source/modules/orbit.utils.md b/doc/source/modules/orbit.utils.md new file mode 100644 index 00000000..feaf05a0 --- /dev/null +++ b/doc/source/modules/orbit.utils.md @@ -0,0 +1,7 @@ +# orbit.utils + +```{eval-rst} +.. automodapi:: orbit.utils + :no-heading: +``` + From 96840436e5ccd50f33a29c3b0566604ab03f9ae8 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 15 Jan 2026 14:23:53 -0500 Subject: [PATCH 19/25] Adjustments to the __init__.py of orbit modules to make the docs compilable When `__all__` is defined, `automodapi` uses it to inform for which elements of the module docs should be generated. If for some reason something defined in `__all__` is not actually importable, then the docs will fail to compile. These adjustments make docs compilable for now. Seeking guidance on whether this is the best way to proceed. --- py/orbit/aperture/__init__.py | 4 +++- py/orbit/bunch_utils/__init__.py | 16 +++++++++++++--- py/orbit/errors/__init__.py | 2 +- py/orbit/fieldtracker/__init__.py | 11 +++++------ py/orbit/orbit_correction/__init__.py | 2 +- py/orbit/py_linac/lattice/__init__.py | 6 +++--- .../SuperFish_3D_RF_FieldReader.py | 2 +- py/orbit/py_linac/rf_field_readers/__init__.py | 6 +++--- py/orbit/rf_cavities/__init__.py | 2 ++ py/orbit/teapot/__init__.py | 1 + py/orbit/time_dep/__init__.py | 3 +++ 11 files changed, 36 insertions(+), 19 deletions(-) diff --git a/py/orbit/aperture/__init__.py b/py/orbit/aperture/__init__.py index cf0f61fa..4289ff27 100644 --- a/py/orbit/aperture/__init__.py +++ b/py/orbit/aperture/__init__.py @@ -8,8 +8,10 @@ from .ApertureLatticeModifications import addTeapotApertureNode from .ApertureLatticeRangeModifications import addCircleApertureSet, addEllipseApertureSet, addRectangleApertureSet +from orbit.core.aperture import Aperture + # from TeapotApertureShapeNode import CircleApertureNode __all__ = [] __all__.append("Aperture") -__all__.append("checkBunch") +# __all__.append("checkBunch") # non-static method of the Aperture Class diff --git a/py/orbit/bunch_utils/__init__.py b/py/orbit/bunch_utils/__init__.py index 88b43d5f..057afaa4 100644 --- a/py/orbit/bunch_utils/__init__.py +++ b/py/orbit/bunch_utils/__init__.py @@ -5,14 +5,24 @@ ## - ParticleIdNumber - Class for adding unique id numbers to particle in a bunch # -from orbit.bunch_utils.particleidnumber import ParticleIdNumber +from .particleidnumber import ParticleIdNumber # This guards against missing numpy. # Should be imporved with some meaningful (and MPI friendly?) warning printed out. try: - from orbit.bunch_utils.serialize import collect_bunch, save_bunch, load_bunch + from .serialize import collect_bunch, save_bunch, load_bunch + from .serialize import BunchDict + from .serialize import FileHandler, NumPyHandler except: pass __all__ = [] -__all__.append("addParticleIdNumbers") +# __all__.append("addParticleIdNumbers") # doesn't exist +__all__.append("ParticleIdNumber") +__all__.append("collect_bunch") +__all__.append("save_bunch") +__all__.append("load_bunch") +__all__.append("BunchDict") +__all__.append("FileHandler") +__all__.append("NumPyHandler") + diff --git a/py/orbit/errors/__init__.py b/py/orbit/errors/__init__.py index 92110bcc..9fcf4d63 100644 --- a/py/orbit/errors/__init__.py +++ b/py/orbit/errors/__init__.py @@ -38,7 +38,7 @@ from orbit.errors.ErrorLatticeModifications import addErrorNodeAsChild_F __all__ = [] -__all__.append("") +# __all__.append("") __all__.append("addErrorNode") __all__.append("addErrorNodeAsChild") __all__.append("addErrorNodeAsChild_I") diff --git a/py/orbit/fieldtracker/__init__.py b/py/orbit/fieldtracker/__init__.py index f2b2d390..3a42371f 100644 --- a/py/orbit/fieldtracker/__init__.py +++ b/py/orbit/fieldtracker/__init__.py @@ -3,12 +3,11 @@ ## ## Classes: - -from . import FieldTracker +from orbit.core.fieldtracker import FieldTracker __all__ = [] __all__.append("FieldTracker") -__all__.append("trackBunch") -__all__.append("FieldParser3D") -__all__.append("BGrid3D") -__all__.append("setPathVariable") +# __all__.append("trackBunch") # non-static method of the FieldTracker Class +# __all__.append("FieldParser3D") # doesn't exist +# __all__.append("BGrid3D") # non-static method of the FieldTracker Class +# __all__.append("setPathVariable") # non-static method of the FieldTracker Class diff --git a/py/orbit/orbit_correction/__init__.py b/py/orbit/orbit_correction/__init__.py index 80f56875..22cec1f6 100644 --- a/py/orbit/orbit_correction/__init__.py +++ b/py/orbit/orbit_correction/__init__.py @@ -13,6 +13,6 @@ __all__ = [] -__all__.append("") +# __all__.append("") __all__.append("orbit") __all__.append("correction") diff --git a/py/orbit/py_linac/lattice/__init__.py b/py/orbit/py_linac/lattice/__init__.py index cab3b3a7..85a9df80 100644 --- a/py/orbit/py_linac/lattice/__init__.py +++ b/py/orbit/py_linac/lattice/__init__.py @@ -68,9 +68,9 @@ __all__.append("RF_Cavity") __all__.append("Sequence") -__all__.append("LinacStructureTree") -__all__.append("LinacStructureSeq") -__all__.append("LinacStuctureNode") +# __all__.append("LinacStructureTree") # doesn't exist +# __all__.append("LinacStructureSeq") +# __all__.append("LinacStuctureNode") __all__.append("BaseRF_Gap") __all__.append("AxisFieldRF_Gap") diff --git a/py/orbit/py_linac/rf_field_readers/SuperFish_3D_RF_FieldReader.py b/py/orbit/py_linac/rf_field_readers/SuperFish_3D_RF_FieldReader.py index 555bfd66..2866d644 100644 --- a/py/orbit/py_linac/rf_field_readers/SuperFish_3D_RF_FieldReader.py +++ b/py/orbit/py_linac/rf_field_readers/SuperFish_3D_RF_FieldReader.py @@ -4,7 +4,7 @@ from orbit.core import orbit_mpi from orbit.core.orbit_mpi import mpi_comm, mpi_datatype, mpi_op -from spacecharge import Grid2D +from orbit.core.spacecharge import Grid2D from orbit.core.orbit_utils import Function, SplineCH, GaussLegendreIntegrator, Polynomial from orbit.utils.fitting import PolynomialFit diff --git a/py/orbit/py_linac/rf_field_readers/__init__.py b/py/orbit/py_linac/rf_field_readers/__init__.py index 47470b31..9921bf1d 100644 --- a/py/orbit/py_linac/rf_field_readers/__init__.py +++ b/py/orbit/py_linac/rf_field_readers/__init__.py @@ -10,12 +10,12 @@ ## 3D filed. It generates the field on the axis for RF_AxisFieldAnalysis # ------------------------------------------------------------------------- -from RF_AxisFieldAnalysis import RF_AxisFieldAnalysis -from SuperFish_3D_RF_FieldReader import SuperFish_3D_RF_FieldReader +from .RF_AxisFieldAnalysis import RF_AxisFieldAnalysis +from .SuperFish_3D_RF_FieldReader import SuperFish_3D_RF_FieldReader __all__ = [] # Classes __all__.append("RF_AxisFieldAnalysis") -__all__.append("SuperFish_3D_RF_FiledReader") +__all__.append("SuperFish_3D_RF_FieldReader") diff --git a/py/orbit/rf_cavities/__init__.py b/py/orbit/rf_cavities/__init__.py index 3bac2839..3c1b3120 100644 --- a/py/orbit/rf_cavities/__init__.py +++ b/py/orbit/rf_cavities/__init__.py @@ -10,6 +10,8 @@ from orbit.rf_cavities.RFNode import Frequency_RFNode from orbit.rf_cavities.RFNode import Harmonic_RFNode from orbit.rf_cavities.RFNode import Barrier_RFNode +from orbit.rf_cavities.RFNode import BRhoDep_Harmonic_RFNode +from orbit.rf_cavities.RFNode import SyncPhaseDep_Harmonic_RFNode from orbit.rf_cavities.RFLatticeModifications import addRFNode __all__ = [] diff --git a/py/orbit/teapot/__init__.py b/py/orbit/teapot/__init__.py index 945450d4..ac2ab3d2 100644 --- a/py/orbit/teapot/__init__.py +++ b/py/orbit/teapot/__init__.py @@ -7,6 +7,7 @@ from .teapot import TEAPOT_Ring from .teapot import BaseTEAPOT from .teapot import BendTEAPOT +from .teapot import BunchWrapTEAPOT from .teapot import DriftTEAPOT from .teapot import FringeFieldTEAPOT from .teapot import KickTEAPOT diff --git a/py/orbit/time_dep/__init__.py b/py/orbit/time_dep/__init__.py index 16afb666..dbf50932 100644 --- a/py/orbit/time_dep/__init__.py +++ b/py/orbit/time_dep/__init__.py @@ -3,5 +3,8 @@ ## ## Classes: ## + +from .time_dep import TIME_DEP_Lattice + __all__ = [] __all__.append("TIME_DEP_Lattice") From baa5b3cccac7b40250ea368ecaad9daad81b1428 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 15 Jan 2026 14:35:22 -0500 Subject: [PATCH 20/25] missing deps, move env file to doc/ --- .github/workflows/docs-build.yml | 2 +- docs-environment.yml => doc/environment.yml | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) rename docs-environment.yml => doc/environment.yml (81%) diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index 7d49d10e..d9074403 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -19,7 +19,7 @@ jobs: activate-environment: po3 channels: conda-forge,defaults auto-update-conda: true - environment-file: docs-environment.yml + environment-file: ./doc/environment.yml - name: Install PyORBIT3 shell: bash -l {0} diff --git a/docs-environment.yml b/doc/environment.yml similarity index 81% rename from docs-environment.yml rename to doc/environment.yml index f27037c3..c7a2e01f 100644 --- a/docs-environment.yml +++ b/doc/environment.yml @@ -8,6 +8,8 @@ dependencies: - python=3.13 - sphinx - sphinx-copybutton + - sphinx-autodoc-typehints + - sphinx-automodapi - myst-parser - breathe - standard-imghdr @@ -18,3 +20,4 @@ dependencies: - meson - pkg-config - ninja + - graphviz From 20d4b7331d69ba9849fc362db020bfb6e636d6fd Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 15 Jan 2026 17:17:37 -0500 Subject: [PATCH 21/25] Restructure for cleaner website --- .github/workflows/docs-build.yml | 4 +-- .gitignore | 2 ++ doc/Makefile | 2 +- doc/source/conf.py | 17 ++++------ doc/source/index.rst | 4 +-- doc/source/modules.rst | 34 ------------------- .../{modules => reference}/orbit.aperture.md | 0 .../{modules => reference}/orbit.bumps.md | 0 .../orbit.bunch_generators.md | 0 .../orbit.bunch_utils.md | 0 .../orbit.collimation.md | 0 .../{modules => reference}/orbit.core.md | 0 .../orbit.diagnostics.md | 0 .../{modules => reference}/orbit.errors.md | 0 .../orbit.fieldtracker.md | 0 .../{modules => reference}/orbit.foils.md | 0 .../orbit.impedances.md | 0 .../{modules => reference}/orbit.injection.md | 0 .../orbit.kickernodes.md | 0 .../{modules => reference}/orbit.lattice.md | 0 .../{modules => reference}/orbit.matching.md | 0 .../orbit.matrix_lattice.md | 0 .../orbit.orbit_correction.md | 0 .../{modules => reference}/orbit.parsers.md | 0 .../{modules => reference}/orbit.py_linac.md | 0 .../orbit.rf_cavities.md | 0 .../orbit.space_charge.md | 0 .../{modules => reference}/orbit.teapot.md | 0 .../orbit.teapot_base.md | 0 .../{modules => reference}/orbit.time_dep.md | 0 .../{modules => reference}/orbit.utils.md | 0 doc/source/reference/py.md | 34 +++++++++++++++++++ 32 files changed, 48 insertions(+), 49 deletions(-) delete mode 100644 doc/source/modules.rst rename doc/source/{modules => reference}/orbit.aperture.md (100%) rename doc/source/{modules => reference}/orbit.bumps.md (100%) rename doc/source/{modules => reference}/orbit.bunch_generators.md (100%) rename doc/source/{modules => reference}/orbit.bunch_utils.md (100%) rename doc/source/{modules => reference}/orbit.collimation.md (100%) rename doc/source/{modules => reference}/orbit.core.md (100%) rename doc/source/{modules => reference}/orbit.diagnostics.md (100%) rename doc/source/{modules => reference}/orbit.errors.md (100%) rename doc/source/{modules => reference}/orbit.fieldtracker.md (100%) rename doc/source/{modules => reference}/orbit.foils.md (100%) rename doc/source/{modules => reference}/orbit.impedances.md (100%) rename doc/source/{modules => reference}/orbit.injection.md (100%) rename doc/source/{modules => reference}/orbit.kickernodes.md (100%) rename doc/source/{modules => reference}/orbit.lattice.md (100%) rename doc/source/{modules => reference}/orbit.matching.md (100%) rename doc/source/{modules => reference}/orbit.matrix_lattice.md (100%) rename doc/source/{modules => reference}/orbit.orbit_correction.md (100%) rename doc/source/{modules => reference}/orbit.parsers.md (100%) rename doc/source/{modules => reference}/orbit.py_linac.md (100%) rename doc/source/{modules => reference}/orbit.rf_cavities.md (100%) rename doc/source/{modules => reference}/orbit.space_charge.md (100%) rename doc/source/{modules => reference}/orbit.teapot.md (100%) rename doc/source/{modules => reference}/orbit.teapot_base.md (100%) rename doc/source/{modules => reference}/orbit.time_dep.md (100%) rename doc/source/{modules => reference}/orbit.utils.md (100%) create mode 100644 doc/source/reference/py.md diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index d9074403..85f4143a 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -33,10 +33,10 @@ jobs: run: | conda activate po3 cd doc - make html + make dirhtml - name: Upload artifact if: ${{ inputs.upload-artifact }} uses: actions/upload-pages-artifact@v3 with: - path: './doc/build/html' + path: './doc/build/dirhtml' diff --git a/.gitignore b/.gitignore index 2f2b3deb..da0ba329 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,5 @@ PyORBIT.egg-info _autosummary/ _api/ _cpp_api/ +doc/source/reference/*.rst +doc/source/reference/*.rst.include diff --git a/doc/Makefile b/doc/Makefile index 85f8baf5..3767ad00 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api "$(SOURCEDIR)"/_cpp_api "$(SOURCEDIR)"/_autosummary + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/reference/*.rst{,.include} "$(SOURCEDIR)"/_autosummary @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index bf87c3c2..0af4ca1a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -24,8 +24,8 @@ "sphinx.ext.coverage", "sphinx.ext.todo", "sphinx.ext.viewcode", - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", + # "sphinx.ext.autodoc", + # "sphinx.ext.autosummary", "sphinx.ext.napoleon", "sphinx_autodoc_typehints", "sphinx_automodapi.automodapi", @@ -39,8 +39,8 @@ napoleon_numpy_docstring = True autosummary_imported_members = True -numpydoc_show_class_members=False -automodapi_toctreedirnm = "_api" +numpydoc_show_class_members = False +automodapi_toctreedirnm = "reference" templates_path = ["_templates"] exclude_patterns = [] @@ -61,10 +61,10 @@ ) exhale_args = { - "containmentFolder": "./_cpp_api", - "rootFileName": "pyorbit_root.rst", + "containmentFolder": "./reference", + "rootFileName": "cpp.rst", "doxygenStripFromPath": "..", - "rootFileTitle": "C++ API", + "rootFileTitle": "C++ API Reference", "fullApiSubSectionTitle": "", "createTreeView": True, "exhaleExecutesDoxygen": True, @@ -83,6 +83,3 @@ "text": "PyORBIT3", }, } -# html_sidebars = { -# "**": ["sidebar-nav-bs"] -# } diff --git a/doc/source/index.rst b/doc/source/index.rst index c2894f70..55503272 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,8 +17,8 @@ :maxdepth: 2 :caption: API Reference - modules - _cpp_api/pyorbit_root + reference/py + reference/cpp Indices and tables diff --git a/doc/source/modules.rst b/doc/source/modules.rst deleted file mode 100644 index c4d0fd44..00000000 --- a/doc/source/modules.rst +++ /dev/null @@ -1,34 +0,0 @@ -Modules -======= - -orbit.aperture -############## - -.. toctree:: - :maxdepth: 2 - - modules/orbit.aperture - modules/orbit.bumps - modules/orbit.bunch_generators - modules/orbit.bunch_utils - modules/orbit.collimation - modules/orbit.core - modules/orbit.diagnostics - modules/orbit.errors - modules/orbit.fieldtracker - modules/orbit.foils - modules/orbit.impedances - modules/orbit.injection - modules/orbit.kickernodes - modules/orbit.lattice - modules/orbit.matching - modules/orbit.matrix_lattice - modules/orbit.orbit_correction - modules/orbit.parsers - modules/orbit.py_linac - modules/orbit.rf_cavities - modules/orbit.space_charge - modules/orbit.teapot - modules/orbit.teapot_base - modules/orbit.time_dep - modules/orbit.utils diff --git a/doc/source/modules/orbit.aperture.md b/doc/source/reference/orbit.aperture.md similarity index 100% rename from doc/source/modules/orbit.aperture.md rename to doc/source/reference/orbit.aperture.md diff --git a/doc/source/modules/orbit.bumps.md b/doc/source/reference/orbit.bumps.md similarity index 100% rename from doc/source/modules/orbit.bumps.md rename to doc/source/reference/orbit.bumps.md diff --git a/doc/source/modules/orbit.bunch_generators.md b/doc/source/reference/orbit.bunch_generators.md similarity index 100% rename from doc/source/modules/orbit.bunch_generators.md rename to doc/source/reference/orbit.bunch_generators.md diff --git a/doc/source/modules/orbit.bunch_utils.md b/doc/source/reference/orbit.bunch_utils.md similarity index 100% rename from doc/source/modules/orbit.bunch_utils.md rename to doc/source/reference/orbit.bunch_utils.md diff --git a/doc/source/modules/orbit.collimation.md b/doc/source/reference/orbit.collimation.md similarity index 100% rename from doc/source/modules/orbit.collimation.md rename to doc/source/reference/orbit.collimation.md diff --git a/doc/source/modules/orbit.core.md b/doc/source/reference/orbit.core.md similarity index 100% rename from doc/source/modules/orbit.core.md rename to doc/source/reference/orbit.core.md diff --git a/doc/source/modules/orbit.diagnostics.md b/doc/source/reference/orbit.diagnostics.md similarity index 100% rename from doc/source/modules/orbit.diagnostics.md rename to doc/source/reference/orbit.diagnostics.md diff --git a/doc/source/modules/orbit.errors.md b/doc/source/reference/orbit.errors.md similarity index 100% rename from doc/source/modules/orbit.errors.md rename to doc/source/reference/orbit.errors.md diff --git a/doc/source/modules/orbit.fieldtracker.md b/doc/source/reference/orbit.fieldtracker.md similarity index 100% rename from doc/source/modules/orbit.fieldtracker.md rename to doc/source/reference/orbit.fieldtracker.md diff --git a/doc/source/modules/orbit.foils.md b/doc/source/reference/orbit.foils.md similarity index 100% rename from doc/source/modules/orbit.foils.md rename to doc/source/reference/orbit.foils.md diff --git a/doc/source/modules/orbit.impedances.md b/doc/source/reference/orbit.impedances.md similarity index 100% rename from doc/source/modules/orbit.impedances.md rename to doc/source/reference/orbit.impedances.md diff --git a/doc/source/modules/orbit.injection.md b/doc/source/reference/orbit.injection.md similarity index 100% rename from doc/source/modules/orbit.injection.md rename to doc/source/reference/orbit.injection.md diff --git a/doc/source/modules/orbit.kickernodes.md b/doc/source/reference/orbit.kickernodes.md similarity index 100% rename from doc/source/modules/orbit.kickernodes.md rename to doc/source/reference/orbit.kickernodes.md diff --git a/doc/source/modules/orbit.lattice.md b/doc/source/reference/orbit.lattice.md similarity index 100% rename from doc/source/modules/orbit.lattice.md rename to doc/source/reference/orbit.lattice.md diff --git a/doc/source/modules/orbit.matching.md b/doc/source/reference/orbit.matching.md similarity index 100% rename from doc/source/modules/orbit.matching.md rename to doc/source/reference/orbit.matching.md diff --git a/doc/source/modules/orbit.matrix_lattice.md b/doc/source/reference/orbit.matrix_lattice.md similarity index 100% rename from doc/source/modules/orbit.matrix_lattice.md rename to doc/source/reference/orbit.matrix_lattice.md diff --git a/doc/source/modules/orbit.orbit_correction.md b/doc/source/reference/orbit.orbit_correction.md similarity index 100% rename from doc/source/modules/orbit.orbit_correction.md rename to doc/source/reference/orbit.orbit_correction.md diff --git a/doc/source/modules/orbit.parsers.md b/doc/source/reference/orbit.parsers.md similarity index 100% rename from doc/source/modules/orbit.parsers.md rename to doc/source/reference/orbit.parsers.md diff --git a/doc/source/modules/orbit.py_linac.md b/doc/source/reference/orbit.py_linac.md similarity index 100% rename from doc/source/modules/orbit.py_linac.md rename to doc/source/reference/orbit.py_linac.md diff --git a/doc/source/modules/orbit.rf_cavities.md b/doc/source/reference/orbit.rf_cavities.md similarity index 100% rename from doc/source/modules/orbit.rf_cavities.md rename to doc/source/reference/orbit.rf_cavities.md diff --git a/doc/source/modules/orbit.space_charge.md b/doc/source/reference/orbit.space_charge.md similarity index 100% rename from doc/source/modules/orbit.space_charge.md rename to doc/source/reference/orbit.space_charge.md diff --git a/doc/source/modules/orbit.teapot.md b/doc/source/reference/orbit.teapot.md similarity index 100% rename from doc/source/modules/orbit.teapot.md rename to doc/source/reference/orbit.teapot.md diff --git a/doc/source/modules/orbit.teapot_base.md b/doc/source/reference/orbit.teapot_base.md similarity index 100% rename from doc/source/modules/orbit.teapot_base.md rename to doc/source/reference/orbit.teapot_base.md diff --git a/doc/source/modules/orbit.time_dep.md b/doc/source/reference/orbit.time_dep.md similarity index 100% rename from doc/source/modules/orbit.time_dep.md rename to doc/source/reference/orbit.time_dep.md diff --git a/doc/source/modules/orbit.utils.md b/doc/source/reference/orbit.utils.md similarity index 100% rename from doc/source/modules/orbit.utils.md rename to doc/source/reference/orbit.utils.md diff --git a/doc/source/reference/py.md b/doc/source/reference/py.md new file mode 100644 index 00000000..997cd266 --- /dev/null +++ b/doc/source/reference/py.md @@ -0,0 +1,34 @@ +# Python API Reference + +## orbit.aperture + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + + orbit.aperture + orbit.bumps + orbit.bunch_generators + orbit.bunch_utils + orbit.collimation + orbit.core + orbit.diagnostics + orbit.errors + orbit.fieldtracker + orbit.foils + orbit.impedances + orbit.injection + orbit.kickernodes + orbit.lattice + orbit.matching + orbit.matrix_lattice + orbit.orbit_correction + orbit.parsers + orbit.py_linac + orbit.rf_cavities + orbit.space_charge + orbit.teapot + orbit.teapot_base + orbit.time_dep + orbit.utils +``` From ea639f57502820cda6c5d8e8acf8ff72af82b3d3 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 15 Jan 2026 17:33:19 -0500 Subject: [PATCH 22/25] Automatically document based on typehints, if available --- doc/source/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index 0af4ca1a..b9496fef 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -36,6 +36,8 @@ "exhale", ] +autodoc_typehints = "description" + napoleon_numpy_docstring = True autosummary_imported_members = True From b10a6fc8d8f9fdf3d67c413f3cd94cf25dbe18a8 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Fri, 16 Jan 2026 14:59:32 -0500 Subject: [PATCH 23/25] fix mesonbuild.md warning --- doc/source/install.md | 82 +++++++++++++++++++++++++++++++++++++- doc/source/reference/py.md | 2 - 2 files changed, 81 insertions(+), 3 deletions(-) diff --git a/doc/source/install.md b/doc/source/install.md index 07b07005..db05c1d2 100644 --- a/doc/source/install.md +++ b/doc/source/install.md @@ -1,5 +1,9 @@ # Installation Guide +```{contents} +:depth: 3 +``` + This guide provides instructions how to install PyORBIT code.
This guide doesn't cover MPI enabled installation.
The following configurations are included in CI testing, versions will change as the runner images progress. @@ -90,7 +94,7 @@ pip install -U meson-python setuptools setuptools-scm ## Build If you plan to modify PyORBIT's code, install it in editable mode. -You will NOT need to rebuild after modifications to the code. [Meson](MesonBuild.md) will rebuild as necessary on import. +You will NOT need to rebuild after modifications to the code. [Meson](meson-primer) will rebuild as necessary on import. ``` pip install --no-build-isolation --editable . ``` @@ -129,3 +133,79 @@ Meson uses PKG_CONFIG to discover packages. It could be useful to help it to fin ```bash PKG_CONFIG_PATH=/opt/lib/pkgconfig pip install --verbose . ``` + +(meson-primer)= +# Meson Primer + +This uses meson-python to build orbit package. + +There is no **setup.py** file, instead we have **meson.build**. +**pyproject.toml** is changed to use meson. + +This is experimental setup that is work in progress. +The pure python part is built with hierarchical **meson.build** files in **py/**. +The C++ setup is combined in one file **src/meson.build**. + +## Main modifications in C++ code +1. **src/libmain/** is not used, still there for reference but will be gone soon. +2. **src/core/** contains one C++ file per module inside _orbit.core_ +3. The files **wrap_XXXX.cc** were modified to correctly reference modules +```cpp +// line +PyObject* mod = PyImport_ImportModule("_bunch"); +// replaced with +PyObject* mod = PyImport_ImportModule("orbit.core.bunch"); +``` + +## Setup + +### 0. Required software + +One needs compilers, python and libfftw (and potentially mpi). +See [PyORBIT3](https://github.com/PyORBIT-Collaboration/PyORBIT3) for external +requirements. + + +### 1. Preparing environment + +First step is to clone the source code from meson branch: + +```bash +git clone -b meson https://github.com/azukov/PyORBIT3.git +``` + +Initialize new virtual environment and install packages + +``` +python -m venv .mes +source .mes/bin/activate +pip install -U pip +pip install -r requirements +``` +Edit **meson.build** and set correct paths/flags for python/fftw3 headers and libraries + +## 2. Build + +To install orbit package in development mode run following: +```bash + pip install --no-build-isolation --editable . +``` +No rebuild is necessary, just edit **py/** or **src/** and meson will rebuild as needed when import happens. + + +### 3. Run examples + +Special examples used for meson testing + +```bash +cd examples/meson +python imports_test.py +python uspas_test.py +``` + +SNS linac example +```bash +cd examples/SNS_Linac/pyorbit3_linac_model/ +python pyorbit3_sns_linac_mebt_hebt2.py +``` + diff --git a/doc/source/reference/py.md b/doc/source/reference/py.md index 997cd266..8e4c7fe5 100644 --- a/doc/source/reference/py.md +++ b/doc/source/reference/py.md @@ -1,7 +1,5 @@ # Python API Reference -## orbit.aperture - ```{eval-rst} .. toctree:: :maxdepth: 2 From 8f4ecba5921039ec8fe00eb70af50b3b37c89e22 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Fri, 16 Jan 2026 15:00:01 -0500 Subject: [PATCH 24/25] Some example docstrings and correcting warnings related to formatting. --- py/orbit/bunch_utils/__init__.py | 5 +- py/orbit/bunch_utils/serialize.py | 91 +++++++++++++++---- .../overlapping_quad_fields_lib.py | 10 +- py/orbit/time_dep/time_dep.py | 4 +- py/orbit/utils/multiDimArray.py | 52 ++++++++--- 5 files changed, 123 insertions(+), 39 deletions(-) diff --git a/py/orbit/bunch_utils/__init__.py b/py/orbit/bunch_utils/__init__.py index 057afaa4..42ea363e 100644 --- a/py/orbit/bunch_utils/__init__.py +++ b/py/orbit/bunch_utils/__init__.py @@ -11,9 +11,9 @@ # Should be imporved with some meaningful (and MPI friendly?) warning printed out. try: from .serialize import collect_bunch, save_bunch, load_bunch - from .serialize import BunchDict + from .serialize import BunchDict, SyncPartDict from .serialize import FileHandler, NumPyHandler -except: +except ImportError: pass __all__ = [] @@ -23,6 +23,7 @@ __all__.append("save_bunch") __all__.append("load_bunch") __all__.append("BunchDict") +__all__.append("SyncPartDict") __all__.append("FileHandler") __all__.append("NumPyHandler") diff --git a/py/orbit/bunch_utils/serialize.py b/py/orbit/bunch_utils/serialize.py index 4e23a7d8..0cbea0f2 100644 --- a/py/orbit/bunch_utils/serialize.py +++ b/py/orbit/bunch_utils/serialize.py @@ -10,6 +10,23 @@ class SyncPartDict(TypedDict): + """A dictionary containing the attributes of the synchronous particle. + + Attributes + ---------- + coords : NDArray[np.float64] + The coordinates (x, px, y, py, z, dE) of the synchronous particle. + kin_energy : float + The kinetic energy of the synchronous particle. + momentum : float + The momentum of the synchronous particle. + beta : float + The beta of the synchronous particle. + gamma : float + The gamma of the synchronous particle. + time : float + The time of the synchronous particle. + """ coords: NDArray[np.float64] kin_energy: np.float64 momentum: np.float64 @@ -19,13 +36,32 @@ class SyncPartDict(TypedDict): class BunchDict(TypedDict): + """A dictionary containing the attributes of a PyOrbit::Bunch object. + + Attributes + ---------- + coords : NDArray[np.float64] + The coordinates (x, px, y, py, z, dE) of the particles in the bunch. + sync_part : SyncPartDict + The attributes of the synchronous particle. + attributes : dict[str, np.float64 | np.int32] + Other attributes of the bunch. + """ coords: NDArray[np.float64] sync_part: SyncPartDict attributes: dict[str, np.float64 | np.int32] class FileHandler(Protocol): - """Protocol for file handlers to read/write bunch data.""" + """Protocol for file handlers to read/write bunch data. + + Methods + _______ + read() -> BunchDict: + Reads the bunch data from the specified directory and returns it as a dictionary. + write(bunch: BunchDict) -> None: + Writes the bunch data to the specified directory. + """ def __init__(self, *args: Any, **kwargs: Any) -> None: ... @@ -36,15 +72,28 @@ def write(self, bunch: BunchDict) -> None: ... class NumPyHandler: """Handler implementing the FileHandler protocol for NumPy binary files. - This handler will create two files in the directory passed to the constructor: - - coords.npy: A memory-mapped NumPy array containing the bunch coordinates. - - attributes.npz: A NumPy archive containing data related to the synchronous particle and other bunch attributes. + + Attributes + ---------- + _coords_fname : str + The name of the file containing the bunch coordinates (default: "coords.npy"). + _attributes_fname : str + The name of the file containing data related to the synchronous particle and other bunch attributes (default: "attributes.npz"). """ _coords_fname = "coords.npy" _attributes_fname = "attributes.npz" - def __init__(self, dir_name: str | pathlib.Path): + def __init__(self, dir_name: str | os.PathLike): + """Constructor for the NumPyHandler class. + + Parameters + ---------- + dir_name + The directory in which to store the bunch data. + + """ + if isinstance(dir_name, str): dir_name = pathlib.Path(dir_name) self._dir_name = dir_name @@ -77,7 +126,7 @@ def write(self, bunch: BunchDict) -> None: def collect_bunch( - bunch: Bunch, output_dir: str | pathlib.Path = "/tmp", return_memmap: bool = True + bunch: Bunch, output_dir: str | os.PathLike = "/tmp", return_memmap: bool = True ) -> BunchDict | None: """Collects attributes from a PyOrbit Bunch across all MPI ranks and returns it as a dictionary. @@ -85,13 +134,15 @@ def collect_bunch( ---------- bunch : Bunch The PyOrbit::Bunch object from which to collect attributes. - output_dir : str | pathlib.Path, optional - The director to use for temporary storage of the bunch coordinates on each MPI rank. - If None, the bunch will be stored in "/tmp". - Note: take care that the temporary files are created in a directory where all MPI ranks have write access. + output_dir : str | os.PathLike, optional + The director to use for temporary storage of the bunch coordinates on each MPI rank (default: "/tmp"). return_memmap : bool, optional Return the bunch coordinates as a memory-mapped NumPy array, otherwise the - entire array is copied into RAM and returned as normal NDArray. Default is True. + entire array is copied into RAM and returned as normal NDArray (default: True). + + Note + ---- + Take care that the temporary files are created in a directory which all MPI ranks have write access. Returns ------- @@ -194,21 +245,24 @@ def collect_bunch( def save_bunch( bunch: Bunch | BunchDict, - output_dir: str | pathlib.Path = "bunch_data/", + output_dir: str | os.PathLike = "bunch_data/", Handler: type[FileHandler] = NumPyHandler, ) -> None: """Saves the collected bunch attributes to a specified directory. + Parameters ---------- bunch_dict : Bunch | BunchDict The PyOrbit::Bunch object or the dictionary containing the collected bunch attributes. output_dir : str, optional - The directory where the bunch data files will be saved. Default is "bunch_data/". + The directory where the bunch data files will be saved (default: "bunch_data/"). Handler : FileHandler, optional - The file handler class to use for writing the bunch data. Default is NumPyHandler. + The file handler class to use for writing the bunch data (default: NumPyHandler). + Returns ------- None + Raises ------ ValueError @@ -238,20 +292,23 @@ def save_bunch( def load_bunch( - input_dir: str | pathlib.Path, Handler: type[FileHandler] = NumPyHandler + input_dir: str | os.PathLike, Handler: type[FileHandler] = NumPyHandler ) -> tuple[Bunch, BunchDict]: """Loads the bunch attributes from a specified directory containing NumPy binary files. + Parameters ---------- - input_dir : str | pathlib.Path + input_dir : str | os.PathLike The directory from which to load the bunch data files. Handler : FileHandler, optional - The file handler class to use for reading the bunch data. Default is NumPyHandler. + The file handler class to use for reading the bunch data (default: NumPyHandler). See `orbit.bunch_utils.file_handler` for available handlers. + Returns ------- BunchDict A dictionary containing the loaded bunch attributes. + Raises ------ FileNotFoundError diff --git a/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py b/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py index 875e5183..4836558a 100644 --- a/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py +++ b/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py @@ -88,10 +88,12 @@ def getFuncDerivative(self, z): class EngeFunction(AbstractQuadFieldSourceFunction): """ - The Enge function with parameters from Berz's paper - M.Berz, B. Erdelyn, K.Makino - Fringe Field Effects in Small Rings of Large Acceptance - Phys. Rev STAB, V3, 124001(2000) + The Enge function with parameters from Berz's paper[1]_. + + References + ---------- + .. [1] M. Berz, B. Erdélyi, and K. Makino, “Fringe field effects in small rings of large acceptance,” Phys. Rev. ST Accel. Beams, vol. 3, no. 12, p. 124001, Dec. 2000, doi: 10.1103/PhysRevSTAB.3.124001. + """ def __init__(self, length_param, acceptance_diameter_param, cutoff_level=0.01): diff --git a/py/orbit/time_dep/time_dep.py b/py/orbit/time_dep/time_dep.py index 2d8483d3..2bf34260 100644 --- a/py/orbit/time_dep/time_dep.py +++ b/py/orbit/time_dep/time_dep.py @@ -15,8 +15,8 @@ class TIME_DEP_Lattice(TEAPOT_Ring): """ The subclass of the TEAPOT_Lattice. - TIME_DEP_Lattice has the ability to set time-dependent - parameters to the Lattice. + + TIME_DEP_Lattice has the ability to set time-dependent parameters to the Lattice. Multi-turn track also available. """ diff --git a/py/orbit/utils/multiDimArray.py b/py/orbit/utils/multiDimArray.py index 6f73c0c4..9dc80eaf 100644 --- a/py/orbit/utils/multiDimArray.py +++ b/py/orbit/utils/multiDimArray.py @@ -1,11 +1,25 @@ -def multiDimDoubleArray(*dims): +def multiDimDoubleArray(*dims: int) -> list[float]: """ - Method. Creates multi-dimensional arrays with doubles, such as a[i][k][j]. - Some examples of the use of this function: - a = multiDimArray(5,10,2) - a = multiDimArray(*[5,10,2]) - a[1][2][1] = 0. - By default all elements are initialized to 0. + Creates multi-dimensional arrays with doubles, such as a[i][k][j]. + + Parameters + ---------- + dims : int + + Returns + ------- + list[float] + + Note + ---- + All elements are initialized to 0. + + Examples + -------- + >>> a = multiDimArray(5,10,2) + >>> a = multiDimArray(*[5,10,2]) # equivalent + >>> a[1][2][1] + 0.0 """ res = [] if len(dims) == 1: @@ -18,14 +32,24 @@ def multiDimDoubleArray(*dims): return res -def multiDimIntArray(*dims): +def multiDimIntArray(*dims: int) -> list[int]: """ - Method. Creates multi-dimensional arrays with integers, such as a[i][k][j]. - Some examples of the use of this function: - a = multiDimArray(5,10,2) - a = multiDimArray(*[5,10,2]) - a[1][2][1] = 0 - By default all elements are initialized to 0. + Creates multi-dimensional arrays with integers, such as a[i][k][j]. + + Parameters + ---------- + dims : int + + Returns + ------- + list[int] + + Examples + -------- + >>> a = multiDimArray(5,10,2) + >>> a = multiDimArray(*[5,10,2]) # equivalent + >>> a[1][2][1] + 0 """ res = [] if len(dims) == 1: From be59d327d066568b3b6fae3a713e82f7e95670c7 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Fri, 16 Jan 2026 17:43:51 -0500 Subject: [PATCH 25/25] needs a space here --- .../py_linac/overlapping_fields/overlapping_quad_fields_lib.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py b/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py index 4836558a..747288f6 100644 --- a/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py +++ b/py/orbit/py_linac/overlapping_fields/overlapping_quad_fields_lib.py @@ -88,7 +88,7 @@ def getFuncDerivative(self, z): class EngeFunction(AbstractQuadFieldSourceFunction): """ - The Enge function with parameters from Berz's paper[1]_. + The Enge function with parameters from Berz's paper [1]_. References ----------