From cddd0bca3fb91998bc4b9d3b842fea3c43fb0923 Mon Sep 17 00:00:00 2001 From: Maxwell-Rosen Date: Thu, 10 Sep 2026 12:35:48 -0400 Subject: [PATCH] Add integration with the postgkyl 2.0 repository and refactor --- .github/workflows/docs.yml | 76 ++++++++++++++++++ .gitignore | 6 +- .readthedocs.yaml | 9 ++- Makefile | 14 +++- README.md | 74 ++++++++++++------ environment.yml | 4 +- scripts/prepare_postgkyl.py | 63 +++++++++++++++ source/conf.py | 66 ++++------------ source/dev/dev-rules.rst | 2 +- source/dev/grhd-equations.rst | 6 +- source/dev/grhd-primitive.rst | 6 +- source/dev/main.rst | 1 + source/dev/vlasov-normalizations.rst | 80 +++++++++---------- source/gkeyll/presentations.rst | 110 ++++++++++++++------------- source/gkeyll/pubs.rst | 106 +++++++++++++------------- source/index.rst | 1 + source/install.rst | 6 +- tests/test_postgkyl_source.py | 78 +++++++++++++++++++ 18 files changed, 468 insertions(+), 240 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 scripts/prepare_postgkyl.py create mode 100644 tests/test_postgkyl_source.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..77afd60 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,76 @@ +name: Documentation + +on: + pull_request: + push: + branches: [main, master] + schedule: + - cron: '23 6 * * *' + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: true + +jobs: + website: + runs-on: ubuntu-latest + timeout-minutes: 30 + env: + MPLBACKEND: Agg + POSTGKYL_REQUIRE_GKEYLL: '1' + VTK_DEFAULT_OPENGL_WINDOW: vtkEGLRenderWindow + LIBGL_ALWAYS_SOFTWARE: '1' + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: pip + cache-dependency-path: source/requirements.txt + - name: Install host documentation tools + run: | + sudo apt-get update + sudo apt-get install -y libegl1 libgl1-mesa-dri + python -m pip install -r source/requirements.txt + - name: Verify main tracking and local preview behavior + run: python -m unittest discover -s tests -v + - name: Fetch Postgkyl main and prepare its documentation + run: python scripts/prepare_postgkyl.py + - name: Test upstream documentation and examples + working-directory: external/postgkyl + run: | + python -m pip install --no-build-isolation -e '.[docs,test]' + python -m pytest tests/test_documentation.py tests/test_examples.py tests/test_docs_build.py + - name: Build the complete website + run: python -m sphinx -W --keep-going -b html source build/html + - uses: actions/upload-artifact@v4 + with: + name: gkeyll-website + path: build/html + if-no-files-found: error + - name: Refresh hosted docs after the daily upstream check + if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' + env: + READTHEDOCS_TOKEN: ${{ secrets.READTHEDOCS_TOKEN }} + run: | + python - <<'PY' + import os + import urllib.request + token = os.environ.get("READTHEDOCS_TOKEN") + if not token: + print("READTHEDOCS_TOKEN is unset; preview built, hosted refresh skipped.") + else: + request = urllib.request.Request( + "https://app.readthedocs.org/api/v3/projects/gkeyll/versions/latest/builds/", + method="POST", headers={"Authorization": f"Token {token}"}) + with urllib.request.urlopen(request, timeout=30) as response: + if response.status != 202: + raise RuntimeError(f"Build trigger returned {response.status}") + print("Requested a Read the Docs rebuild from Postgkyl main.") + PY diff --git a/.gitignore b/.gitignore index 11aba60..5d3484c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,7 @@ *~ build/* -*.bp \ No newline at end of file +*.bp +/external/ +/source/postgkyl/ +__pycache__/ +/.venv/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 94ab422..3aaabed 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -8,12 +8,19 @@ version: 2 # Set the version of Python and other tools you might need build: os: ubuntu-22.04 + apt_packages: + - libegl1 + - libgl1-mesa-dri tools: - python: "3.8" + python: "3.12" + jobs: + post_install: + - VTK_DEFAULT_OPENGL_WINDOW=vtkEGLRenderWindow LIBGL_ALWAYS_SOFTWARE=1 python scripts/prepare_postgkyl.py # Build documentation in the docs/ directory with Sphinx sphinx: configuration: source/conf.py + fail_on_warning: true # We recommend specifying your dependencies to enable reproducible builds: # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html diff --git a/Makefile b/Makefile index 4e1181a..583a0b4 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,9 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = python -msphinx +PYTHON ?= python +SPHINXBUILD = $(PYTHON) -msphinx +POSTGKYL_PREPARE_ARGS ?= SPHINXPROJ = gkyl SOURCEDIR = source BUILDDIR = build @@ -12,9 +14,15 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile postgkyl html + +postgkyl: + $(PYTHON) scripts/prepare_postgkyl.py $(POSTGKYL_PREPARE_ARGS) + +html: postgkyl + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) # 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) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/README.md b/README.md index 37a0fab..e37a48e 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,62 @@ -This is the documentation and tutorials for the -[gkyl](https://github.com/ammarhakim/gkyl) project +# Gkeyll documentation +This repository hosts the Gkeyll website, including documentation generated +from [Postgkyl main](https://github.com/gkeyllorg/postgkyl/tree/main). -In order to build the docs locally, one needs -[sphinx](https://www.sphinx-doc.org/en/master/) and the -[furo](https://github.com/pradyunsg/furo) theme. +Use **Python 3.12**, Git, Make, and a C compiler. From this repository: -We recommend creating a virtual environment[^1] and installing the dependencies -through [conda](https://conda.io/miniconda.html): ```bash -conda env create -f environment.yml +python -m venv .venv +source .venv/bin/activate +python -m pip install -r source/requirements.txt +make html SPHINXOPTS="-W --keep-going" ``` -The environment is then activated with -```bash -conda activate gkyl-doc -``` +Open `build/html/index.html`. `make html` fetches Postgkyl **main** into +`external/postgkyl`, installs it with its documentation dependencies and native +Gkeyll bridge, executes its examples, and stages its documentation in +`source/postgkyl/`. The first build needs network access and can take several +minutes. Both directories are ignored build inputs/outputs; edit Postgkyl +content in its own repository. A later build fetches main again. A dirty +managed checkout is refused rather than overwritten. + +For a local Postgkyl change before it reaches main: -However, one can also attempt to install the dependencies directly to current -`conda` environment using: ```bash -conda install --file source/requirements.txt +make html POSTGKYL_PREPARE_ARGS="--checkout /path/to/postgkyl" SPHINXOPTS="-W --keep-going" ``` -With the dependencies installed, the documentation is simply built with `make -html` from the `gkyl-doc` directory. The desired HTML file is than in the -`build` directory. +Add `--no-install` only when that exact checkout is already installed with +`pip install --no-build-isolation -e '.[docs]'` in the active environment. +The generator checks the imported package location and requires its native +bridge. Its documentation, examples, and test data all come from the same +checkout. The resulting pages record the source commit for traceability; +that record does not pin subsequent builds. + +Read the Docs runs the same preparation script after installing host +requirements. `.readthedocs.yaml` selects Python 3.12 and treats Sphinx warnings +as errors. Merge the Postgkyl documentation implementation into its main branch +before enabling this host change, since the host requires its build script. + +GitHub Actions tests pull requests, pushes, and a daily checkout of Postgkyl +main. It runs Postgkyl's documentation and example tests, validates the +standalone build and downloaded examples, then builds the complete website +with warnings as errors and uploads an HTML preview artifact. + +For automatic hosted refreshes after successful daily checks, configure the +GitHub Actions repository secret `READTHEDOCS_TOKEN` with a token authorized to +trigger builds of the `gkeyll` Read the Docs project. Without it the scheduled +checks and preview artifacts still run; hosting updates on normal Read the +Docs builds. The manual Actions workflow also requests a hosted refresh when +the secret is configured. Tokens are never used on pull requests. + +The gallery now runs both the Python scripts and their paired CLI pipelines, +checks raster pixels/GIF timings or Plotly trace data/layout, and publishes +both results. The Python API is generated as one page per callable/property. +Interactive Plotly HTML is copied beside the referring pages by Postgkyl's +shared Sphinx extension. -[^1]: Note that `conda` needs to be initialized before environments can be used. - This is the last step of the `conda` installation, but the current default - behavior is _not_ to perform the initialization. It can be done afterwards - using `conda init [shell name]`, e.g., `conda init fish` with the fantastic - [fish](https://fishshell.com/) shell. \ No newline at end of file +PyVista screenshots require OpenGL. CI and Read the Docs install `libegl1` +and `libgl1-mesa-dri` and select `VTK_DEFAULT_OPENGL_WINDOW=vtkEGLRenderWindow` +with `LIBGL_ALWAYS_SOFTWARE=1` for headless Linux. Local machines with a working +OpenGL display can use their usual renderer. diff --git a/environment.yml b/environment.yml index 43751c6..6d8a5b6 100644 --- a/environment.yml +++ b/environment.yml @@ -2,10 +2,10 @@ name: gkyl-doc channels: - defaults dependencies: - - python>=3.11 + - python=3.12 - pip - sphinx>=5.0.2 - furo>=2024.8.6 - pip: # add here only pip-packages that are not available in conda/conda-forge! E.g.: - - sphinx-immaterial>=0.11.8 \ No newline at end of file + - sphinx-immaterial>=0.11.8 diff --git a/scripts/prepare_postgkyl.py b/scripts/prepare_postgkyl.py new file mode 100644 index 0000000..0f0cc0e --- /dev/null +++ b/scripts/prepare_postgkyl.py @@ -0,0 +1,63 @@ +"""Fetch Postgkyl main, install it, and generate this website's Postgkyl section. + +An explicit --checkout uses a local working tree for cross-repository previews. +Normal builds always fetch main; they never reuse a pinned source revision. +""" + +from __future__ import annotations + +import argparse +from pathlib import Path +import subprocess +import sys + + +def prepare(site: Path, checkout: Path | None, no_install: bool) -> None: + if checkout is None: + checkout = site / "external/postgkyl" + if not checkout.exists(): + checkout.parent.mkdir(parents=True, exist_ok=True) + subprocess.run([ + "git", "clone", "--depth", "1", "--branch", "main", + "https://github.com/gkeyllorg/postgkyl.git", str(checkout), + ], check=True) + else: + dirty = subprocess.check_output([ + "git", "-C", str(checkout), "status", "--porcelain", + ], text=True) + if dirty.strip(): + raise RuntimeError(f"Refusing to change dirty checkout: {checkout}") + subprocess.run([ + "git", "-C", str(checkout), "fetch", "--depth", "1", + "origin", "main", + ], check=True) + subprocess.run([ + "git", "-C", str(checkout), "checkout", "--detach", "FETCH_HEAD", + ], check=True) + checkout = checkout.resolve() + generator = checkout / "scripts/build_docs.py" + if not generator.is_file(): + raise RuntimeError( + "Postgkyl main must contain scripts/build_docs.py. Merge the " + "Postgkyl documentation implementation before deploying this host.") + if not no_install: + subprocess.run([ + sys.executable, "-m", "pip", "install", "numpy>=2.2.6", + "setuptools", "wheel", + ], check=True) + subprocess.run([ + sys.executable, "-m", "pip", "install", "--no-build-isolation", + "-e", f"{checkout}[docs]", + ], check=True) + subprocess.run([ + sys.executable, str(generator), "--output", str(site / "source/postgkyl"), + ], cwd=checkout, check=True) + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--checkout", type=Path, help="Use a local Postgkyl checkout") + parser.add_argument("--no-install", action="store_true", + help="Use dependencies already installed in this environment") + args = parser.parse_args() + prepare(Path(__file__).resolve().parents[1], args.checkout, args.no_install) diff --git a/source/conf.py b/source/conf.py index 7eff59e..bf1d5a7 100644 --- a/source/conf.py +++ b/source/conf.py @@ -20,6 +20,8 @@ import os import sys sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('postgkyl/_ext')) +postgkyl_doc_root = 'postgkyl' #import sphinx_rtd_theme @@ -38,6 +40,9 @@ 'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.autosectionlabel', + 'sphinx.ext.napoleon', + 'myst_parser', + 'postgkyl_docs', # 'sphinx_immaterial', ] @@ -48,7 +53,9 @@ # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'} +autodoc_typehints = 'none' +autosectionlabel_prefix_document = True # The master toctree document. master_doc = 'index' @@ -82,7 +89,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] +exclude_patterns = ['postgkyl/_inputs/**', 'postgkyl/_ext/**'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -112,7 +119,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static', 'postgkyl/_static'] +html_static_path = ['_static'] # html_context = { @@ -184,55 +191,8 @@ 'Miscellaneous'), ] +# Furo options; the previous Material-theme options were not used by Furo. html_theme_options = { - "light_logo": "logoG1.png", # dark logo for light mode - "dark_logo": "logoG1_w.png", # white logo for dark mode - "icon": { - "repo": "fontawesome/brands/github", - "edit": "material/file-edit-outline", - }, - "site_url": "https://gkeyll.readthedocs.io/en/latest/", - "repo_url": "https://github.com/ammarhakim/gkylzero", - "repo_name": "Gkeyll", - "globaltoc_collapse": True, - "features": [ - "navigation.expand", - "navigation.sections", - "navigation.top", - "search.share", - "toc.follow", - "toc.sticky", - "content.tabs.link", - "announce.dismiss", - ], - "palette": [ - { - "media": "(prefers-color-scheme: light)", - "scheme": "default", - "primary": "blue", - "accent": "indigo", - "toggle": { - "icon": "material/lightbulb-outline", - "name": "Switch to dark mode", - }, - }, - { - "media": "(prefers-color-scheme: dark)", - "scheme": "slate", - "primary": "blue", - "accent": "indigo", - "toggle": { - "icon": "material/lightbulb", - "name": "Switch to light mode", - }, - }, - ], - "toc_title_is_page_title": True, - "social": [ - { - "icon": "fontawesome/brands/github", - "link": "https://github.com/gkeyllorg/gkyl-doc", - "name": "Source on github.com", - }, - ], + "light_logo": "logoG1.png", + "dark_logo": "logoG1_w.png", } diff --git a/source/dev/dev-rules.rst b/source/dev/dev-rules.rst index 72f5baa..03dd7ef 100644 --- a/source/dev/dev-rules.rst +++ b/source/dev/dev-rules.rst @@ -35,4 +35,4 @@ and concerns should be directed to the core Gkeyll Dev Team. PR. That person ideally should build the code and make check, but this is not a requirement. - Always be sure to follow our - :ref:`Design and Code Review Process `. \ No newline at end of file + `Design and Code Review Process `_. \ No newline at end of file diff --git a/source/dev/grhd-equations.rst b/source/dev/grhd-equations.rst index b2d5479..53812f3 100644 --- a/source/dev/grhd-equations.rst +++ b/source/dev/grhd-equations.rst @@ -7,7 +7,7 @@ For the purpose of supporting the (prototype) general relativistic hydrodynamics capabilities currently available within the Moment app, Gkeyll solves a particular hyperbolic conservation law form of the hydrodynamics equations in curved spacetime known colloquially as the :math:`{3 + 1}` "Valencia" formulation, due originally to -[Banyuls1997]_, and based (as the name suggests) on the :math:`{3 + 1}` "ADM" formalism +[Banyuls1997-grhd-equations]_, and based (as the name suggests) on the :math:`{3 + 1}` "ADM" formalism of [Arnowitt1959]_. This technical note details exactly how Gkeyll performs and represents the :math:`{3 + 1}` decomposition of the general relativistic hydrodynamics equations, and hence introduces the specific form of the equations solved by the Moment @@ -310,7 +310,7 @@ respectively. The :math:`{3 + 1}` "Valencia" formulation ------------------------------------------ -The :math:`{3 + 1}` "Valencia" formulation of [Banyuls1997]_ is now derived by +The :math:`{3 + 1}` "Valencia" formulation of [Banyuls1997-grhd-equations]_ is now derived by considering the specific case of the ADM energy and momentum conservation equations for a perfect relativistic fluid, and expressing the resulting equations in terms of the spatial fluid velocity :math:`\mathbf{v}` (i.e. the fluid velocity @@ -512,7 +512,7 @@ and the baryon number conservation equation: References ---------- -.. [Banyuls1997] F. Banyuls, J. A. Font, J. M. Ibáñez, J. M. Martí and +.. [Banyuls1997-grhd-equations] F. Banyuls, J. A. Font, J. M. Ibáñez, J. M. Martí and J. A. Miralles, "Numerical {3 + 1} General Relativistic Hydrodynamics: A Local Characteristic Approach", *The Astrophysical Journal* **476** (1): 221-231, 1997. diff --git a/source/dev/grhd-primitive.rst b/source/dev/grhd-primitive.rst index 5b3654b..57fce10 100644 --- a/source/dev/grhd-primitive.rst +++ b/source/dev/grhd-primitive.rst @@ -28,7 +28,7 @@ non-relativistic case. Thus, for a generic equation of state, it is argued by hydrodynamics cannot be represented as a closed-form algebraic operation, and instead requires one to perform some kind of (potentially higher-dimensional) root-finding operation. To this end, Gkeyll employs a certain "robustified" variant of the algorithm -proposed by [Eulderink1995]_, which has been specifically modified to accommodate low +proposed by [Eulderink1995-grhd-primitive]_, which has been specifically modified to accommodate low densities, low pressures, and high values of the Lorentz factor, without going unstable, whilst still retaining the favorable convergence properties of the original Eulderink and Mellema algorithm in less extreme cases. In this short technical note, we will @@ -79,7 +79,7 @@ now becomes: c_s = \sqrt{\frac{\Gamma P}{\rho \left( 1 + \left( \frac{P}{\rho} \right) \left( \frac{\Gamma}{\Gamma - 1} \right) \right)}}. -The approach advocated by [Eulderink1995]_ is then to use a non-linear root-finding +The approach advocated by [Eulderink1995-grhd-primitive]_ is then to use a non-linear root-finding algorithm (namely the one-dimensional Newton-Raphson method) to find the roots of the following quartic polynomial in :math:`\xi`: @@ -265,7 +265,7 @@ References .. [Marti2003] J. M. Martí and E. Müller, "Numerical Hydrodynamics in Special Relativity", *Living Reviews in Relativity* **6** (7). 2003. -.. [Eulderink1995] F. Eulderink and G. Mellema, "General Relativistic Hydrodynamics +.. [Eulderink1995-grhd-primitive] F. Eulderink and G. Mellema, "General Relativistic Hydrodynamics with a Roe solver", *Astronomy and Astrophysics Supplement Series* **110**: 587-623. 1995. diff --git a/source/dev/main.rst b/source/dev/main.rst index 0e092d0..9201c72 100644 --- a/source/dev/main.rst +++ b/source/dev/main.rst @@ -25,3 +25,4 @@ Developer notes grhd-primitive tokamak-topology valgrind + regression diff --git a/source/dev/vlasov-normalizations.rst b/source/dev/vlasov-normalizations.rst index 9c429e2..e18a465 100644 --- a/source/dev/vlasov-normalizations.rst +++ b/source/dev/vlasov-normalizations.rst @@ -1,10 +1,10 @@ .. _vlasovNorm: -Normalized units for the Vlasov-Maxwell system +Normalized units for the Vlasov-Maxwell system ++++++++++++++++++++++++++++++++++++++++++++++ -Many equation systems in Gkeyll are implemented in unit-full forms for ease of cross comparison -with experiments. As such, equation systems such as the Vlasov-Maxwell system of equations are +Many equation systems in Gkeyll are implemented in unit-full forms for ease of cross comparison +with experiments. As such, equation systems such as the Vlasov-Maxwell system of equations are defined in Gkeyll in S.I units: .. math:: @@ -14,12 +14,12 @@ defined in Gkeyll in S.I units: \epsilon_0\mu_0\frac{\partial \mathbf{E}}{\partial t} - \nabla_{\mathbf{x}} \times \mathbf{B} = -\mu_0 \mathbf{J}, \qquad & \nabla_{\mathbf{x}} \cdot \mathbf{E} = \frac{\rho_c}{\epsilon_0} \\ \rho_c = \sum_s q_s \int_{-\infty}^{\infty} f_s \thinspace d\mathbf{v}, \qquad & \mathbf{J} = \sum_s q_s \int_{-\infty}^{\infty} \mathbf{v} f_s \thinspace d\mathbf{v}. -The expectation is thus that a user define these various constants: -:math:`\epsilon_0, \mu_0, q_s, m_s,` etc. Utilizing the provided Lib.Constants library -in Gkeyll allows a user to use universal constants provided by the National Institute of -Standards and Technology. However, one may not always wish to run simulations with the -unit-full system. Instead, one can consider a normalized set of equations. -A natural choice for the normalization of the Vlasov-Maxwell system of equations +The expectation is thus that a user define these various constants: +:math:`\epsilon_0, \mu_0, q_s, m_s,` etc. Utilizing the provided Lib.Constants library +in Gkeyll allows a user to use universal constants provided by the National Institute of +Standards and Technology. However, one may not always wish to run simulations with the +unit-full system. Instead, one can consider a normalized set of equations. +A natural choice for the normalization of the Vlasov-Maxwell system of equations would redefine all the relevant quantities as follows, .. math:: @@ -41,12 +41,12 @@ where \omega_{pe} & = \sqrt{\frac{e^2 n}{m_e \epsilon_0}}, \\ d_e & = \frac{c}{\omega_{pe}}, -are the speed of light, electron plasma frequency, and the electron skin depth respectively. -Note that the charge normalization means that in a proton-electron plasma, :math:`\tilde{q}_s = \pm 1`, -and the density normalization is such that in a quasi-neutral plasma, the initial density -of each species is 1.0. We can also check that the electric and magnetic field normalizations -are reasonable by making sure that the normalization has the correct units for the electric -and magnetic fields in S.I. units, +are the speed of light, electron plasma frequency, and the electron skin depth respectively. +Note that the charge normalization means that in a proton-electron plasma, :math:`\tilde{q}_s = \pm 1`, +and the density normalization is such that in a quasi-neutral plasma, the initial density +of each species is 1.0. We can also check that the electric and magnetic field normalizations +are reasonable by making sure that the normalization has the correct units for the electric +and magnetic fields in S.I. units, .. math:: @@ -62,11 +62,11 @@ With these normalizations, the Vlasov-Maxwell system of equations then becomes, \frac{\partial \tilde{\mathbf{E}}}{\partial \tau} - \nabla_{\boldsymbol \chi} \times \tilde{\mathbf{B}} = -\tilde{\mathbf{J}}, \quad & \nabla_{\boldsymbol \chi} \cdot \mathbf{E} = \tilde{\rho_c} \\ \tilde{\rho_c} = \sum_s \tilde{q}_s \int_{-\infty}^{\infty} f_s \thinspace d\boldsymbol \nu, \quad & \tilde{\mathbf{J}} = \sum_s \tilde{q}_s \int_{-\infty}^{\infty} \boldsymbol \nu f_s \thinspace d\boldsymbol \nu. -This system of equations has the obvious advantage that universal constants, such as :math:`\epsilon_0`, -are eliminated. In doing so, one does not need to worry about the propagation of round off error from, -for example, the accumulation of the current to the electric field in the Ampere-Maxwell law, -:math:`E^{n+1} = E^{n} + \Delta t \mathbf{J}/\epsilon_0` becomes :math:`E^{n+1} = E^{n} + \Delta t \tilde{\mathbf{J}}`. -Given Gkeyll's unit-full representation, a simple way to force the Vlasov-Maxwell solver to "use" +This system of equations has the obvious advantage that universal constants, such as :math:`\epsilon_0`, +are eliminated. In doing so, one does not need to worry about the propagation of round off error from, +for example, the accumulation of the current to the electric field in the Ampere-Maxwell law, +:math:`E^{n+1} = E^{n} + \Delta t \mathbf{J}/\epsilon_0` becomes :math:`E^{n+1} = E^{n} + \Delta t \tilde{\mathbf{J}}`. +Given Gkeyll's unit-full representation, a simple way to force the Vlasov-Maxwell solver to "use" these units is to specify the following parameters be equal to 1.0, .. math:: @@ -76,12 +76,12 @@ these units is to specify the following parameters be equal to 1.0, \omega_{pe} = 1.0, & \qquad d_e = 1.0, \\ n_0 = 1.0. & -With the above parameters set to 1.0, then Vlasov-Maxwell simulations require only a few parameters -to be completely determined. In a proton-electron plasma these are: the proton-to-electron mass ratio, -:math:`m_p/m_e`, the proton-to-electron temperature ratio, :math:`T_p/T_e`, the ratio of some -characteristic velocity, such as the electron Alfv\'en speed, to the speed of light, :math:`v_{A_e}/c`, -and the plasma beta of either the protons or the electrons, :math:`\beta`. It is often convenient -with this normalized system to use the combination of the ratio of the electron Alfv\'en speed +With the above parameters set to 1.0, then Vlasov-Maxwell simulations require only a few parameters +to be completely determined. In a proton-electron plasma these are: the proton-to-electron mass ratio, +:math:`m_p/m_e`, the proton-to-electron temperature ratio, :math:`T_p/T_e`, the ratio of some +characteristic velocity, such as the electron Alfv\'en speed, to the speed of light, :math:`v_{A_e}/c`, +and the plasma beta of either the protons or the electrons, :math:`\beta`. It is often convenient +with this normalized system to use the combination of the ratio of the electron Alfv\'en speed to the speed of light and the plasma beta to derive the temperature in normalized units, like so, .. math:: @@ -89,23 +89,23 @@ to the speed of light and the plasma beta to derive the temperature in normalize \frac{v_{A_e}}{c} & = \frac{|\mathbf{B}|/\sqrt{n_e m_e \mu_0}}{c} \qquad \rightarrow \qquad \tilde{v_{A_e}} = |\tilde{\mathbf{B}}|, \\ \beta_e & = \frac{ 2 n_e T_e \mu_0}{|\mathbf{B}|^2} \qquad \rightarrow \qquad \tilde{T_e} = \tilde{\beta_e} \tilde{v_{A_e}}^2/2.0, -assuming the plasma is quasineutral and thus, :math:`n_0 = 1.0` for both the protons and electrons. -The proton beta and proton temperature then follow from the specified proton-to-electron temperature -ratio. It is recommended that the user initialize Maxwellian distribution functions using this derived +assuming the plasma is quasineutral and thus, :math:`n_0 = 1.0` for both the protons and electrons. +The proton beta and proton temperature then follow from the specified proton-to-electron temperature +ratio. It is recommended that the user initialize Maxwellian distribution functions using this derived temperature, so as to avoid the ambiguity of the user's definition of the thermal velocity, .. math:: f_{\textrm{maxwellian}} = \frac{\tilde{n_s}}{\sqrt{2 \pi \tilde{T_s}/\tilde{m_s}}} \exp \left (-\tilde{m_s} \frac{(\boldsymbol\nu - \tilde{\mathbf{u}_s})^2}{2 \tilde{T_s}} \right ). -Whether the user ultimately elects to use :math:`v_{th_s} = \sqrt{2 T_s/m_s}` or -:math:`v_{th_s} = \sqrt{T_s/m_s}` is of no consequence to the initialization of the simulation, -and likely only to manifest in the user's specification of the velocity space extents. Indeed, if -a user employs the LTE (local thermodynamic equilibrium) initial condition module, then -the expected input is the temperature, **not the thermal velocity**. +Whether the user ultimately elects to use :math:`v_{th_s} = \sqrt{2 T_s/m_s}` or +:math:`v_{th_s} = \sqrt{T_s/m_s}` is of no consequence to the initialization of the simulation, +and likely only to manifest in the user's specification of the velocity space extents. Indeed, if +a user employs the LTE (local thermodynamic equilibrium) initial condition module, then +the expected input is the temperature, **not the thermal velocity**. -These normalized units can also be utilized in multi-fluid simulations of plasmas---see -the :doc:`multi-fluid quickstart example `, which defines +These normalized units can also be utilized in multi-fluid simulations of plasmas---see +the :doc:`multi-fluid quickstart example `, which defines .. math:: @@ -117,8 +117,8 @@ and thus the derived quantities are .. math:: - \omega_{pe} = 5.0, \qquad d_e = 1.0/5.0, \qquad \omega_{pi} = 1.0, \qquad d_i = 1.0. + \omega_{pe} = 5.0, \qquad d_e = 1.0/5.0, \qquad \omega_{pi} = 1.0, \qquad d_i = 1.0. -Note that in this case the ion scales are defined as the reference scales, and quantities such as the -inverse electron plasma frequency, :math:`\omega_{pe}^{-1}`, and electron inertial length are -:math:`\sqrt{m_e/m_i}` smaller than the inverse ion plasma frequency and ion inertial length. +Note that in this case the ion scales are defined as the reference scales, and quantities such as the +inverse electron plasma frequency, :math:`\omega_{pe}^{-1}`, and electron inertial length are +:math:`\sqrt{m_e/m_i}` smaller than the inverse ion plasma frequency and ion inertial length. diff --git a/source/gkeyll/presentations.rst b/source/gkeyll/presentations.rst index 36d1e02..93182a5 100644 --- a/source/gkeyll/presentations.rst +++ b/source/gkeyll/presentations.rst @@ -1,6 +1,6 @@ Presentations +++++++++++++ -You can browse a `folder of pdf / PowerPoint / Keynote files `_ of Gkeyll presentations, or click on links below. +You can browse a `folder of pdf / PowerPoint / Keynote files `__ of Gkeyll presentations, or click on links below. .. note:: @@ -9,122 +9,124 @@ You can browse a `folder of pdf / PowerPoint / Keynote files `_, `video recording `_ +- "Gyrokinetic equilibria for high field magnetic mirrors with multiscale methods", M. ROsen, Realta Fusion Open Science Meeting, virtual, April 2026. `pdf `__. -- "Postgkyl tutorial", P. Cagas, Virginia Tech. seminar, November 2022. `pdf `_ +- "An introduction to the Gkeyll simulation framework for both research and education", J. Juno, Open Source Software for Fusion Energy conference, Munich, Germany, March 2026. `pdf `__, `video recording `__ + +- "Postgkyl tutorial", P. Cagas, Virginia Tech. seminar, November 2022. `pdf `__ 2026 -- "Using Gkeyll as a self-consistent gyrokinetic predictive tool for tokamak edge turbulence", A.C.D. Hoffmann, Open Source Software for Fusion Energy conference, Munich, Germany, March 2026. `pdf `_ +- "Using Gkeyll as a self-consistent gyrokinetic predictive tool for tokamak edge turbulence", A.C.D. Hoffmann, Open Source Software for Fusion Energy conference, Munich, Germany, March 2026. `pdf `__ 2025 2024 - "Direct Comparison of Gyrokinetic and Fluid Simulations of a Prospective Spherical Tokamak Pilot Plant Scrape-Off Layer", Akash Shukla, US-EU Transport Task Force, April 2024. - `pdf `_ + `pdf `__ 2023 -- "Novel fluid-kinetic modeling: a parallel-kinetic-perpendicular-moment model for diverse plasma applications", Jimmy Juno, *Princeton Center for Theoretical Science: New perspectives in numerical methods for high-energy multiscale astrophysics*, April 2023. `pdf `_, `Keynote (with movies) `_ +- "Novel fluid-kinetic modeling: a parallel-kinetic-perpendicular-moment model for diverse plasma applications", Jimmy Juno, *Princeton Center for Theoretical Science: New perspectives in numerical methods for high-energy multiscale astrophysics*, April 2023. `pdf `__, `Keynote (with movies) `__ + +- "Benchmarking the Parallel-Kinetic Perpendicular-Moment Model for Magnetized Plasmas", Jason TenBarge, *Princeton Center for Theoretical Science: New perspectives in numerical methods for high-energy multiscale astrophysics*, April 2023. `pdf `__, `Keynote (with movies) `__ -- "Benchmarking the Parallel-Kinetic Perpendicular-Moment Model for Magnetized Plasmas", Jason TenBarge, *Princeton Center for Theoretical Science: New perspectives in numerical methods for high-energy multiscale astrophysics*, April 2023. `pdf `_, `Keynote (with movies) `_ - 2022 -- "Tracking blobs to analyze turbulence in the edge of tokamak", Rupak Mukherjee, *6th Asia Pacific Conference on Plasma Physics (Virtual)*, October 2022. - `pdf `_, - `Keynote (with movies) `_ +- "Tracking blobs to analyze turbulence in the edge of tokamak", Rupak Mukherjee, *6th Asia Pacific Conference on Plasma Physics (Virtual)*, October 2022. + `pdf `__, + `Keynote (with movies) `__ 2021 - "Prioritizing, Leveraging, and Disseminating Fundamental Algorithms Research", Jimmy Juno, *PPPL CSD Seminar*, November 2021. - `pdf `_ + `pdf `__ -- "Modelling AUG scrape-off-layer plasma with full-f continuum Electromagnetic Gyrokinetic simulation", Rupak Mukherjee, *APS DPP Annual Meeting*, November 2021. - `pdf `_, - `Keynote (with movies) `_, - `video recording of talk `_ +- "Modelling AUG scrape-off-layer plasma with full-f continuum Electromagnetic Gyrokinetic simulation", Rupak Mukherjee, *APS DPP Annual Meeting*, November 2021. + `pdf `__, + `Keynote (with movies) `__, + `video recording of talk `__ -- "Electromagnetic full-f continuum gyrokinetic simulation of plasma turbulence in scrape-off layer of ASDEX Upgrade", Rupak Mukherjee, *19th European Fusion Theory Conference (Virtual in Consorzio RFX)*, October 2021. - `pdf `_, - `Keynote (with movies) `_ +- "Electromagnetic full-f continuum gyrokinetic simulation of plasma turbulence in scrape-off layer of ASDEX Upgrade", Rupak Mukherjee, *19th European Fusion Theory Conference (Virtual in Consorzio RFX)*, October 2021. + `pdf `__, + `Keynote (with movies) `__ -- "Electromagnetic full-f continuum gyrokinetic simulation of plasma turbulence in scrape-off layer of ASDEX Upgrade tokamak", Rupak Mukherjee, *5th Asia Pacific Conference on Plasma Physics (Virtual)*, September 2021. - `pdf `_, - `Keynote (with movies) `_, - `video recording of talk `_ +- "Electromagnetic full-f continuum gyrokinetic simulation of plasma turbulence in scrape-off layer of ASDEX Upgrade tokamak", Rupak Mukherjee, *5th Asia Pacific Conference on Plasma Physics (Virtual)*, September 2021. + `pdf `__, + `Keynote (with movies) `__, + `video recording of talk `__ -- "Modelling AUG scrape-off-layer plasma with full-f continuum Electromagnetic Gyrokinetic simulation", Rupak Mukherjee, *Virtual 25th Joint EU-US TTF Meeting*, September 2021. - `pdf `_ +- "Modelling AUG scrape-off-layer plasma with full-f continuum Electromagnetic Gyrokinetic simulation", Rupak Mukherjee, *Virtual 25th Joint EU-US TTF Meeting*, September 2021. + `pdf `__ - "Simulation of AUG scrape-off-layer plasma with full-f continuum Electromagnetic Gyrokinetic simulation", Rupak Mukherjee, *Sherwood Fusion Theory conference*, August 2021. - `pdf `_, - `Keynote (with movies) `_, - `video recording of talk `_ + `pdf `__, + `Keynote (with movies) `__, + `video recording of talk `__ - "Initial Gkeyll simulations of Scrape-Off-Layer Turbulence in ASDEX-U", Rupak Mukherjee, *MPPC Meeting*, January 2021. - `pdf `_, - `Keynote (with movies) `_, - `video recording of talk `_ + `pdf `__, + `Keynote (with movies) `__, + `video recording of talk `__ 2020 - "Electromagnetic full-f gyrokinetic simulation of ASDEX SOL turbulence with discontinuous Galerkin method", Rupak Mukherjee, *APS DPP Annual Meeting*, November 2020. - `pdf `_, - `Keynote (with movies) `_, - `video recording of talk `_ + `pdf `__, + `Keynote (with movies) `__, + `video recording of talk `__ - "Investigating magnetic fluctuations in gyrokinetic simulations of tokamak SOL turbulence", Noah Mandell, *APS DPP Annual Meeting*, November 2020. - `pdf `_, - `Keynote (with movies) `_, - `video recording of talk `_ -- "A Deep Dive into the Distribution Function: Understanding Phase + `pdf `__, + `Keynote (with movies) `__, + `video recording of talk `__ +- "A Deep Dive into the Distribution Function: Understanding Phase Space Dynamics Using Continuum Vlasov-Maxwell Simulations", Jimmy - Juno, *APS DPP Annual Meeting*, November 2020. `Keynote - `_ + Juno, *APS DPP Annual Meeting*, November 2020. `Keynote + `__ - "Balancing Flexibility and Usability in the Gkeyll Simulation Framework", Jimmy Juno, *APS DPP Annual Meeting*, November 2020 `Keynote - `_ + `__ - "Studies of plasma sheaths using novel numerical schemes with self-consistent emitting walls and Fokker-Planck collisions", Petr Cagas, *APS DPP Annual Meeting*, November 2020. - `pdf `_, - `video recording `_ + `pdf `__, + `video recording `__ - "Kinetic Boltzmann modeling of neutral transport for a continuum gyrokinetic code", Tess Bernard, *APS DPP Annual Meeting*, November 2020. `pdf - `_ + `__ - "Alias-free, Matrix-free, and Quadrature-free Discontinuous Galerkin Algorithms for (Plasma) Kinetic Equations", Ammar Hakim. *SuperComputing 2020*, November 2020. `ppt - `_ + `__ - "Investigating magnetic fluctuations in gyrokinetic simulations of tokamak SOL turbulence", Noah Mandell, *PPPL Theory Research & Review Seminar*, October 2020. - `pdf `_, - `Keynote (with movies) `_ + `pdf `__, + `Keynote (with movies) `__ - "Investigating magnetic fluctuations in tokamak SOL turbulence using Gkeyll gyrokinetic simulations", Noah Mandell, *PPPL Monthly Research Meeting*, October 2020. - `pdf `_, - `Keynote (with movies) `_ + `pdf `__, + `Keynote (with movies) `__ - "Magnetic fluctuations in gyrokinetic simulations of tokamak SOL turbulence", Noah Mandell, *Journal of Plasma Physics Frontiers colloquium series*, April 2020. `pdf - `_, + `__, `Keynote (with movies) - `_ -- "Initial SOL turbulence results from the Gkeyll code, including first electromagnetic effects", Greg Hammett, *AUG Seminar*, Garching, January 2020. `pdf `_, `ppt (with movies) `_ + `__ +- "Initial SOL turbulence results from the Gkeyll code, including first electromagnetic effects", Greg Hammett, *AUG Seminar*, Garching, January 2020. `pdf `__, `ppt (with movies) `__ 2019 - "Continuum Electromagnetic Gyrokinetic Simulations of Turbulence in the Tokamak Scrape-Off Layer and Laboratory Devices", Ammar Hakim, *APS Division of Plasma Physics*, Fort Lauderdale, 2019. -- "Tests of a Discontinuous Galerkin scheme for Hamiltonian systems in non-canonical coordinates", Rupak Mukherjee, *APS Division of Plasma Physics*, Fort Lauderdale, 2019. `pdf `_ +- "Tests of a Discontinuous Galerkin scheme for Hamiltonian systems in non-canonical coordinates", Rupak Mukherjee, *APS Division of Plasma Physics*, Fort Lauderdale, 2019. `pdf `__ - "Gyrokinetic continuum simulations of plasma turbulence in the Texas Helimak", Tess Bernard, *Sherwood Fusion Theory Conference*, Princeton, April 2019. - "Gyrokinetic continuum simulations of plasma turbulence in the Texas Helimak", Tess Bernard, *24th Joint US-EU Transport Task Force Meeting*, Austin, March 2019. 2016 -- "Full-F gyrokinetic simulations of the LAPD device with open field lines and sheath boundary conditions", Greg W. Hammett, Eric L. Shi, Ammar Hakim, Oxford Plasma Theory Group Seminar, Nov. 17, 2016. `pdf `_, `ppt `_ +- "Full-F gyrokinetic simulations of the LAPD device with open field lines and sheath boundary conditions", Greg W. Hammett, Eric L. Shi, Ammar Hakim, Oxford Plasma Theory Group Seminar, Nov. 17, 2016. `pdf `__, `ppt `__ Not very complete. more to be added... diff --git a/source/gkeyll/pubs.rst b/source/gkeyll/pubs.rst index 547feea..2f5bbcb 100644 --- a/source/gkeyll/pubs.rst +++ b/source/gkeyll/pubs.rst @@ -2,12 +2,12 @@ Publications and theses +++++++++++++++++++++++ A good source of various benchmarks and other tests is A. Hakim's -`Simulation Journal `_ and its `github -webpage `_. +`Simulation Journal `__ and its `github +webpage `__. We have also compiled input files for the simulations reported in publications in `this repository -`_. Note that this +`__. Note that this collection is incomplete as not all authors have desposited their input files with us. @@ -30,41 +30,41 @@ Doctoral Dissertations - John Rodman (2025, November). "Discontinuous Galerkin Studies of Collisional Dynamics in Continuum-Kinetic Plasma". Ph.D dissertation, Virginia Tech. `Access - here. `_ + here. `__ - McGreivy, Nick (2024, May) "Differentiable Programming for Computational Plasma Physics" - Ph.D. dissertation, Princeton University, 2024. `arXiv:2410.11161 `_ + Ph.D. dissertation, Princeton University, 2024. `arXiv:2410.11161 `__ - Bradshaw, K. (2024, February 23) "Emitting Wall Boundary Conditions in Continuum Kinetic Simulations: Unlocking the Effects of Energy-Dependent Material Emission on the Plasma Sheath." Ph.D. dissertation, Virginia Polytechnic Institute and State University, 2024. - `Access here. `_ + `Access here. `__ - Mandell, N. R. (2021, March 26) "Magnetic Fluctuations in Gyrokinetic Simulations of Scrape-Off Layer Turbulence". - Ph.D. dissertation, Princeton University, 2021. `arXiv:2103.16062 `_ + Ph.D. dissertation, Princeton University, 2021. `arXiv:2103.16062 `__ - Juno, J. (2020, March 27) "A Deep Dive into the Distribution Function: Understanding Phase Space Dynamics Using Continuum Vlasov-Maxwell Simulations". Ph. D. dissertation, University of Maryland, College Park, 2020. `arXiv:2005.13539 - `_ + `__ - Bernard, T. N. "Discontinuous Galerkin Modeling of Plasma Turbulence in a Simple Magnetized Torus". Ph. D. dissertation, The University of Texas at Austin, 2019. `PDF - `_ + `__ - Ng, J. "Fluid closures for the modeling of reconnection and instabilities in magnetotail current sheets". Ph.D. dissertation, Princeton University, 2018. `PDF - `_ + `__ - Cagas, P. (2018, July 30). "Continuum kinetic simulations of plasma sheaths and instabilities". Ph.D. dissertation, Virginia Polytechnic Institute and State University, 2018. - ``_ + ``__ - Shi, E. L. (2017, August 24). "Gyrokinetic Continuum Simulation of Turbulence in Open-Field-Line Plasmas", Ph.D. dissertation, - Princeton University, 2017 `arXiv:1708.07283 `_ + Princeton University, 2017 `arXiv:1708.07283 `__ - Wang, L. (2014, Aug 30). "Integrating Kinetic Physics in Fluid Models for Magnetic Reconnection". Ph.D. dissertation, University of @@ -81,104 +81,104 @@ Algorithms papers - Maxwell H. Rosen, Manaure Francisquez, Gregory W. Hammett. "An explicit multiscale pseudo orbit-averaging time integration - algorithm", `arXiv:2604.00121. `_ + algorithm", `arXiv:2604.00121. `__ - James Juno, Grant Johnson, Alexander Philippov, Ammar Hakim, Alexander Chernoglazov, Shuzhe Zeng (2026). "Modeling of Relativistic Plasmas with a Conservative Discontinuous Galerkin - Method", `arXiv:2602.17487. `_ + Method", `arXiv:2602.17487. `__ - Jonathan Gorard, Ammar Hakim, Jimmy Juno (2026). "BEACONS: Bounded-Error, Algebraically-Composable Neural Solvers for Partial Differential Equations", - `arXiv:2602.14853. `_ + `arXiv:2602.14853. `__ - Mustafa Aggul, Manaure Francisquez, Daniel R. Reynolds, Sylvia Amihere (2026). "Super Time Stepping Methods for Diffusion using Discontinuous-Galerkin Spatial Discretizations", - `arXiv:2601.14508. `_ + `arXiv:2601.14508. `__ - Grant Johnson, Ammar Hakim, James Juno (2025). "A Conservative Discontinuous Galerkin Algorithm for Particle Kinetics on Smooth - Manifolds", `arXiv:2512.05298. `_ + Manifolds", `arXiv:2512.05298. `__ - Jonathan Gorard, James Juno, Ammar Hakim (2025). "Beyond GRMHD: A Robust Numerical Scheme for Extended, Non-Ideal General Relativistic Multifluid Simulations", - `arXiv:2510.26019. `_ + `arXiv:2510.26019. `__ - Akash Shukla, Ammar Hakim, James Juno, Gregory Hammett, Manaure Francisquez (2025). "Constructing Field Aligned Coordinate Systems for Gyrokinetic Simulations of Tokamaks in X-point Geometries", - `arXiv:2510.21676. `_ + `arXiv:2510.21676. `__ - Francisquez, M., Cagas, P., Shukla, A., Juno, J., Hammett, G. W. (2025). "Conservative velocity mappings for discontinuous Galerkin kinetics", - `arXiv:2505.10754. `_ + `arXiv:2505.10754. `__ - Juno J., Hakim A., TenBarge J. M. (2025). "A parallel-kinetic-perpendicular-moment model for magnetised plasmas", - *Journal of Plasma Physics* **91**, 5:E129. ``_ + *Journal of Plasma Physics* **91**, 5:E129. ``__ - Johnson G., Hakim A., Juno J. (2025). "A moment-conserving discontinuous Galerkin representation of the relativistic Maxwellian distribution", - *Journal of Plasma Physics* **91**, 5:E130. ``_ + *Journal of Plasma Physics* **91**, 5:E130. ``__ - Gorard, J., Hakim, A. (2025). "Shock with Confidence: Formal Proofs of Correctness for Hyperbolic Partial Differential Equation Solvers", - `arXiv:2503.13877. `_ + `arXiv:2503.13877. `__ - Gorard, J., Hakim, A., Juno, J., TenBarge, J. M. (2024). "A Tetrad-First Approach to Robust Numerical Algorithms in General - Relativity", `arXiv:2410.02549 `_ + Relativity", `arXiv:2410.02549 `__ - Nick McGreivy and Ammar Hakim (2024) "Weak baselines and reporting biases lead to overoptimism in machine learning for fluid-related partial differential equations". Nature Machine Intelligence volume - 6, 1256–1269 (2024) ``_ + 6, 1256–1269 (2024) ``__ - Francisquez, M., Mandell, N. R., Hakim, A., Hammett, G. W. (2024) "Conservative discontinuous Galerkin interpolation: sheared boundary conditions", - *Compute Physics Communications* **298**, 109109. ``_ + *Compute Physics Communications* **298**, 109109. ``__ - Nick McGreivy, Ammar Hakim, "Invariant preservation in machine learned PDE solvers via error correction", - `arXiv:2303.16110. `_ + `arXiv:2303.16110. `__ - Cagas, P and Hakim, A and Srinivasan, B. (2021) "A boundary value “reservoir problem” and boundary conditions for multi-moment multifluid simulations - of sheaths", *Physics of Plasmas* **28.1**. ``_ + of sheaths", *Physics of Plasmas* **28.1**. ``__ - Hakim, A and Juno, J. (2020). "Alias-free, Matrix-free, and Quadrature-free Discontinuous Galerkin Algorithms for (Plasma) Kinetic Equations". *SC20: Proceedings of the International Conference for High Performance Computing, Networking, Storage and Analysis*, IEEE - Press. ``_ + Press. ``__ - Francisquez, M., Bernard, T. N., Mandell, N. R., Hammett, G. W., Hakim, A. (2020). "Conservative discontinuous Galerkin scheme of a gyro-averaged Dougherty collision operator", *Nuclear Fusion*, - **60**, (9). ``_ + **60**, (9). ``__ - Hakim, A., Francisquez, M., Juno, J., & Hammett, G. W. (2020). "Conservative discontinuous Galerkin schemes for nonlinear Dougherty–Fokker–Planck collision operators", *Journal of Plasma - Physics*, **86**, (4). ``_ + Physics*, **86**, (4). ``__ - Wang, L., Hakim, A., Ng, J., Dong, C., & Germaschewski, K. (2020). "Exact and locally implicit source term solvers for multifluid-Maxwell systems", - *Journal of Computational Physics*, **415**, 109510. ``_ + *Journal of Computational Physics*, **415**, 109510. ``__ - Cagas, P., Hakim, A., & Srinivasan, B. (2020). "Plasma-material boundary conditions for discontinuous Galerkin continuum-kinetic simulations, with a focus on secondary electron emission", *Journal - of Computational Physics*, **406**, 109215. ``_ + of Computational Physics*, **406**, 109215. ``__ - Mandell, N. R., Hakim, A., Hammett, G. W., & Francisquez, M. (2020). "Electromagnetic full-f gyrokinetics in the tokamak edge with discontinuous Galerkin methods", *Journal of Plasma Physics*, - **86**. ``_ + **86**. ``__ - Juno, J., Hakim, A., TenBarge, J., Shi, E., & Dorland, W. (2018). "Discontinuous Galerkin algorithms for fully @@ -187,7 +187,7 @@ Algorithms papers - Hakim, A., Hammett, G. W., Shi, E. L. (2014). "On discontinuous Galerkin discretizations of second-order - derivatives", `arXiv:1405.5907 `_ + derivatives", `arXiv:1405.5907 `__ Physics papers -------------- @@ -204,23 +204,23 @@ Physics papers - Maxwell H. Rosen, Manaure Francisquez, Ammar Hakim, Gregory W. Hammett. (2026). "Gyrokinetic equilibria of high temperature superconducting magnetic mirrors", `arXiv:2604.11684 - `_ + `__ - Hoffmann, A.C.D., Bernard, T.N., Francisquez, M., Hammett, G. W., Hakim, A., Boedo, J., Rizkallah, R., Tsui, C. K., the TCV team (2026). "Towards fully predictive gyrokinetic full-f simulations: validation and triangularity studies in TCV". *Nucl. Fusion*, **66**, 046022. - ``_ + ``__ - Joshua Pawlak, James Juno, Jason M. TenBarge (2026), "Line-Tied Flux Rope Relaxation and Reconnection: A 3D Kinetic Case Study", - `arXiv:2603.05855 `_ + `arXiv:2603.05855 `__ - Liang Wang, Chuanfei Dong, Yi-Min Huang, Yue Yuan, Xinmin Li, Yang Zhang (2026), "Transition of Magnetic Reconnection Regimes in Partially Ionized Plasmas", `arXiv:2602.23683 - `_ + `__ - Bradshaw, K., Hakim, A. H., Juno, J., Pawlak, J., TenBarge, J. M., & Bhattacharjee, A. (2026). "Capturing secondary kinetic instabilities @@ -232,58 +232,58 @@ Physics papers - Lise Hanebring, James Juno, Ammar Hakim, Jason M. TenBarge, Istvan Pusztai (2026). "From Weibel seeds to collisionless dynamos beyond pair-plasmas", `arXiv:2601.10472 - `_ + `__ - C. R. Skolar, B. Srinivasan (2026). "Effects of parallel magnetic fields on sheaths near biased electrodes in a highly collisional Z-pinch plasma". `arXiv:2601.10039 - `_ + `__ - Akash Shukla, Jonathan Roeltgen, Michael Kotschenreuther, David R. Hatch, Manaure Francisquez, James Juno, Tess N. Bernard, Ammar Hakim, Gregory W. Hammett, Swadesh M. Mahajan (2025). "Gyrokinetic Simulations of a Low Recycling Scrape-off Layer without a Lithium Target", `arXiv:2511.09437 - `_ + `__ - Zeng, S., Philippov, A., Juno, J., Beloborodov, A. M., Popova, E. (2025). "Origin of Pulsed Radio Emission from Magnetars", - `arXiv:2509.13419 `_ + `arXiv:2509.13419 `__ - Liu, D., Juno, J., Hammett, G. W., Hakim, A., Shukla, A., Francisquez, M. (2025). "Axisymmetric Gyrokinetic Simulation of ASDEX-Upgrade Scrape-off Layer Using a Conservative Implicit BGK Collision Operator", - `arXiv:2507.22821 `_ + `arXiv:2507.22821 `__ - Roeltgen, J. P., Juno, J., Kotschenreuther, M., Bernard, T. N., Shukla, A., Francisquez, M., Hakim, A., Hammett, G. W., Power, D., Hatch, D. R. (2025). "A kinetic line-driven radiation operator and its application to gyrokinetics", *Nuclear Fusion* **65**, 106020. - ``_ + ``__ - Skolar, C. R., Bradshaw, K., Francisquez, M., Murillo, L., Krishna Kumar, V., Srinivasan, B. (2025). "General kinetic ion-induced electron emission model for metallic walls applied to biased Z-pinch electrodes", *Physics of Plasmas* - **32**, 082306. ``_ + **32**, 082306. ``__ - Gorard, J., Juno, J., Hakim, A. (2025). "Hydrodynamic and Electromagnetic Discrepancies between Neutron Star and Black Hole Spacetimes", - *Physical Review Letters* (submitted); `arXiv:2505.05299. `_ + *Physical Review Letters* (submitted); `arXiv:2505.05299. `__ - Shukla, A., Roeltgen, J., Kotschenreuther, M., Juno, J., Bernard, T. N., Hakim, A., Hammett, G. W., Hatch, D. R., Mahajan, S. M., Francisquez, M. (2025). "Direct Comparison of Gyrokinetic and Fluid Scrape-Off-Layer Simulations of a Prospective Spherical Tokamak Pilot Plant", *AIP Advances* **15**, 075121. - ``_ + ``__ - Bradshaw, K., Hakim, A., Srinivasan, B. (2025). "Effects of oxidation and impurities in lithium surfaces on the emitting wall plasma sheath", - *Physics of Plasmas* **32**, 063506. ``_ + *Physics of Plasmas* **32**, 063506. ``__ - Bernard, T. N., Halpern, F. D., Francisquez, M., Hammett, G. W., Marinoni, A. (2024). "Plasma edge and scrape-off layer turbulence in gyrokinetic simulations of negative triangularity plasmas." *Plasma Physics and Controlled Fusion*, **66**, 115017. - ``_ + ``__ - Conley, S. A., Juno, J., TenBarge, J. M., Barbhuiya, M. H., Cassak, P. A., Howes, G. G., @@ -345,7 +345,7 @@ Physics papers - Rodman, J., Cagas, P., Hakim, A., Srinivasan, B. (2022). "A kinetic interpretation of the classical Rayleigh-Taylor instability", *Physical Review E*, - `PhysRevE.105.065209 `_. + `PhysRevE.105.065209 `__. - Francisquez, M., Juno, J., Hakim, A., Hammett, G. W., Ernst, D. R. (2022). "Improved multispecies Dougherty collisions" @@ -361,7 +361,7 @@ Physics papers - Mandell, N. R., Hammett, G. W., Hakim, A., Francisquez, M. (2022). "Reduction of transport due to magnetic shear in gyrokinetic simulations of the scrape-off layer", `arXiv:2112.14220 - `_. Under review in Plasma Physics + `__. Under review in Plasma Physics and Controlled Fusion. - Mandell, N. R., Hammett, G. W., Hakim, A., Francisquez, M. (2022). @@ -378,7 +378,7 @@ Physics papers - Wang, L., Hakim, A., Srinivasan, B., Juno, J. (2021). "Electron cyclotron drift instability and anomalous transport: two-fluid moment theory and modeling", `arXiv:2107.09874 - `_. + `__. - Jenab, S. M., Brodin, G., Juno, J., Kourakis, I. (2021). "Ultrafast Electron Holes in Plasma Phase Space Dynamics", *Scientific diff --git a/source/index.rst b/source/index.rst index d1569ae..51cb0de 100644 --- a/source/index.rst +++ b/source/index.rst @@ -189,6 +189,7 @@ Other Pages install quickstart + postgkyl/index gkeyll/pubs gkeyll/presentations dev/main diff --git a/source/install.rst b/source/install.rst index 0e52583..ea245b9 100644 --- a/source/install.rst +++ b/source/install.rst @@ -26,7 +26,7 @@ instructions below assume that you have a working C compiler (such as ``gcc`` or GPUs) installed on your machine. The first step in any :math:`\texttt{Gkeyll}` installation is to clone the repository -from GitHub (`which can be found here `_): +from GitHub (`which can be found here `__): .. code-block:: bash @@ -411,9 +411,9 @@ Installing :math:`\texttt{postgkyl}` :math:`\texttt{postgkyl}` is :math:`\texttt{Gkeyll}`'s custom-built Python post-processing and visualization pipeline, capable of performing many advanced analysis -and plotting tasks on :math:`\texttt{Gkeyll}` simulation output. For further information on how to use these capabilities, please refer to this `tutorial presentation by Petr Cagas <_static/Postgkyl_Petr.pdf>`_. To build +and plotting tasks on :math:`\texttt{Gkeyll}` simulation output. For further information on how to use these capabilities, please refer to this `tutorial presentation by Petr Cagas <_static/Postgkyl_Petr.pdf>`__. To build :math:`\texttt{postgkyl}` from source, one must first clone the repository from GitHub -(`which can be found here `_): +(`which can be found here `__): .. code-block:: bash diff --git a/tests/test_postgkyl_source.py b/tests/test_postgkyl_source.py new file mode 100644 index 0000000..d76d9ad --- /dev/null +++ b/tests/test_postgkyl_source.py @@ -0,0 +1,78 @@ +"""Check main tracking against a local Git remote, without network or pip.""" + +import os +from pathlib import Path +import runpy +import subprocess +import tempfile +import unittest +from unittest.mock import patch + + +prepare = runpy.run_path(str( + Path(__file__).resolve().parents[1] / "scripts/prepare_postgkyl.py"))["prepare"] + + +class MainTrackingTests(unittest.TestCase): + def setUp(self): + self.temporary = tempfile.TemporaryDirectory() + self.addCleanup(self.temporary.cleanup) + self.root = Path(self.temporary.name) + self.remote = self.root / "remote" + self.site = self.root / "site" + self.site.mkdir() + subprocess.run(["git", "init", "-b", "main", str(self.remote)], + check=True, capture_output=True) + (self.remote / "scripts").mkdir() + (self.remote / "scripts/build_docs.py").write_text(''' +import argparse +from pathlib import Path +import subprocess +parser = argparse.ArgumentParser() +parser.add_argument("--output", type=Path) +output = parser.parse_args().output +output.mkdir(parents=True, exist_ok=True) +(output / "revision").write_text(subprocess.check_output( + ["git", "rev-parse", "HEAD"], text=True)) +''') + self.commit("initial") + self.environment = patch.dict(os.environ, { + "GIT_CONFIG_COUNT": "1", + "GIT_CONFIG_KEY_0": f"url.{self.remote.as_uri()}.insteadOf", + "GIT_CONFIG_VALUE_0": "https://github.com/gkeyllorg/postgkyl.git", + "GIT_ALLOW_PROTOCOL": "file", + }) + self.environment.start() + self.addCleanup(self.environment.stop) + + def commit(self, message): + subprocess.run(["git", "-C", str(self.remote), "add", "."], + check=True, capture_output=True) + subprocess.run(["git", "-C", str(self.remote), "-c", "user.name=Docs", + "-c", "user.email=docs@example.invalid", "commit", "-m", message], + check=True, capture_output=True) + return subprocess.check_output( + ["git", "-C", str(self.remote), "rev-parse", "HEAD"], text=True) + + def test_second_build_fetches_new_main_commit(self): + prepare(self.site, None, True) + result = self.site / "source/postgkyl/revision" + first = result.read_text() + (self.remote / "new-guide.rst").write_text("New guide") + second = self.commit("new guide on main") + prepare(self.site, None, True) + self.assertNotEqual(first, second) + self.assertEqual(result.read_text(), second) + + def test_dirty_managed_checkout_is_preserved(self): + prepare(self.site, None, True) + edited = self.site / "external/postgkyl/scripts/build_docs.py" + edited.write_text("Local work") + with self.assertRaisesRegex(RuntimeError, "dirty checkout"): + prepare(self.site, None, True) + self.assertEqual(edited.read_text(), "Local work") + + def test_explicit_checkout_builds_without_fetching(self): + prepare(self.site, self.remote, True) + self.assertFalse((self.site / "external").exists()) + self.assertTrue((self.site / "source/postgkyl/revision").is_file())