diff --git a/.github/workflows/dependencies/documentation.sh b/.github/workflows/dependencies/documentation.sh new file mode 100755 index 0000000..782ca1d --- /dev/null +++ b/.github/workflows/dependencies/documentation.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# +# Copyright 2020 The AMReX Community +# +# License: BSD-3-Clause-LBNL +# Authors: Andrew Myers + +set -eu -o pipefail + +# `man apt.conf`: +# Number of retries to perform. If this is non-zero APT will retry +# failed files the given number of times. +echo 'Acquire::Retries "3";' | sudo tee /etc/apt/apt.conf.d/80-retries + +sudo apt-get update + +sudo apt-get install -y --no-install-recommends\ + build-essential \ + pandoc \ + doxygen \ + texlive \ + texlive-latex-extra \ + texlive-lang-cjk \ + tex-gyre \ + latexmk + diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..ff72508 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,30 @@ +name: Build and Deploy + +on: + push: + branches-ignore: + - 'dependabot/**' + pull_request: + +concurrency: + group: ${{ github.ref }}-${{ github.head_ref }}-docs + cancel-in-progress: true + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v6 + with: + persist-credentials: false + + - name: Dependencies + run: | + .github/workflows/dependencies/documentation.sh + python3 -m pip install --upgrade pip + python3 -m pip install sphinx==5.0.0 sphinx_rtd_theme + + - name: Install and Build + run: | + ./build_docs.sh \ No newline at end of file diff --git a/Docs/README.md b/Docs/README.md new file mode 100644 index 0000000..f18e7cd --- /dev/null +++ b/Docs/README.md @@ -0,0 +1 @@ +Online documentation is available at https://amrex-codes.github.io/amrex/docs_html/. diff --git a/Docs/Readme.sphinx b/Docs/Readme.sphinx new file mode 100644 index 0000000..a99db64 --- /dev/null +++ b/Docs/Readme.sphinx @@ -0,0 +1,51 @@ +To update the online AMReX documentation using sphinx: + + 1. Checkout the development branch of AMReX + + 2. Go to amrex/Docs/sphinx_documentation/source and edit the relevant .rst file(s). + + 3. Commit your changes. + +The GitHub action script will build the html pages and commit them to AMReX's gh-pages repo for you. If you would like to +preview the html locally, you can: + + 4. Go back into amrex/Docs/sphinx_documentation. + + 5. Type "make html". This will build new html files in amrex/Docs/sphinx_documentation/build/html + +********************************************************************************** + +If you would like to build the web pages locally, you will need Python, the Sphinx software, and the "Read the Docs" theme. + +If you have conda, you can install the necessary packages as follows: + + 1. Type "conda install sphinx" + + 2. Type "conda install sphinx_rtd_theme" + +If you don't have a conda Python installation, you get one by doing the following: + + 1. Go to https://conda.io/miniconda.html and download the Python 3.6 64-bit (bash installer), "Miniconda3-latest-Linux-x86_64.sh". Save this script to your hard drive. + + 2. Type "bash Miniconda3-latest-Linux-x86_64.sh" and follow the installation prompts. + + 3. The install script will prompt you to add some commands to your .bashrc that add the miniconda install location to your PATH environment variable. + If Bash is your default shell, choose "yes". Otherwise, you will need to manually do the same for your shell of choice. + + 4. Either open a new terminal, or re-source the configuration file you just added to. E.g., for bash: + source ~/.bashrc + +You should now be able to successfully "make html" in amrex/Docs/sphinx_documentation. + +If you would like to make a pdf document from the *rst files, first + +sudo apt-get install latexmk +(if you are using macOS, latexmk is installed via the TexLive Utility) + +Then in the amrex/Docs/sphinx_documentation directory, type + +make latexpdf +(if you have the slimmed-down latex install, then you need to also install the following packages via TexLive Utility: tabulary, varwidth, framed, wrapfig, capt-of, needspace, courier) + + +This will create amrex/Docs/sphinx_documentation/build/latex/amrex.pdf diff --git a/Docs/sphinx_documentation/Makefile b/Docs/sphinx_documentation/Makefile new file mode 100644 index 0000000..5478394 --- /dev/null +++ b/Docs/sphinx_documentation/Makefile @@ -0,0 +1,26 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +PYTHON ?= python +SPHINXOPTS = +SPHINXBUILD = $(PYTHON) -msphinx +SPHINXPROJ = amrex +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 + +clean: + rm -rf build ../Doxygen/xml source/class source/file + rm -f source/classlist.rst source/filelist.rst + rm -rf source/*_files.rst + +# 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/Docs/sphinx_documentation/source/LoadBalancing.rst b/Docs/sphinx_documentation/source/LoadBalancing.rst new file mode 100644 index 0000000..3ef1427 --- /dev/null +++ b/Docs/sphinx_documentation/source/LoadBalancing.rst @@ -0,0 +1,56 @@ +.. role:: cpp(code) + :language: c++ + +.. role:: fortran(code) + :language: fortran + +.. _sec:load_balancing: + +Load Balancing +-------------- + +The process of load balancing is typically independent of the process of grid creation; +the inputs to load balancing are a given set of grids with a set of weights +assigned to each grid. (The exception to this is the KD-tree approach in which the +grid creation process is governed by trying to balance the work in each grid.) + +Single-level load balancing algorithms are sequentially applied to each AMR level independently, +and the resulting distributions are mapped onto the ranks taking into account the weights +already assigned to them (assign heaviest set of grids to the least loaded rank). Note that the +load of each process is measured by how much memory has already been allocated, not how much memory +will be allocated. Therefore the following code is not recommended because it tends to generate +non-optimal distributions. + +.. highlight:: c++ + +:: + + for (int lev = 0; lev < nlevels; ++lev) { + // build DistributionMapping for Level lev + } + for (int lev = 0; lev < nlevels; ++lev) { + // build MultiFabs for Level lev + } + +Instead, one should do, + +.. highlight:: c++ + +:: + + for (int lev = 0; lev < nlevels; ++lev) { + // build DistributionMapping for Level lev + // build MultiFabs for Level lev + } + +Distribution options supported by AMReX include the following; the default is SFC: + +- Knapsack: the default weight of a grid in the knapsack algorithm is the number of grid cells, + but AMReX supports the option to pass an array of weights -- one per grid -- or alternatively + to pass in a MultiFab of weights per cell which is used to compute the weight per grid. + +- SFC: enumerate grids with a space-filling Z-morton curve, then partition the + resulting ordering across ranks in a way that balances the load. + +- Round-robin: sort grids and assign them to ranks in round-robin fashion -- specifically + FAB i is owned by CPU i%N where N is the total number of MPI ranks. diff --git a/Docs/sphinx_documentation/source/ManagingGridHierarchy_Chapter.rst b/Docs/sphinx_documentation/source/ManagingGridHierarchy_Chapter.rst new file mode 100644 index 0000000..1912c71 --- /dev/null +++ b/Docs/sphinx_documentation/source/ManagingGridHierarchy_Chapter.rst @@ -0,0 +1,43 @@ +.. role:: cpp(code) + :language: c++ + +.. _Chap:ManagingGridHierarchy: + +Gridding and Load Balancing +=========================== + +AMReX provides a great deal of generality when it comes to how to decompose the +computational domain into individual logically rectangular grids, and how to distribute +those grids to MPI ranks. We use the phrase "load balancing" here to refer to the combined process +of grid creation (and re-creation when regridding) and distribution of grids to MPI ranks. + +Even for single-level calculations, AMReX provides the flexibility to have different size grids, +more than one grid per MPI rank, and different strategies for distributing the grids to MPI ranks. + +For multi-level calculations, the same principles for load balancing apply as in single-level calculations, +but there is additional complexity in how to tag cells for refinement and how to create the +union of grids at levels > 0 where that union most likely does not cover the computational domain. + +See :ref:`sec:grid_creation` for grids are created, i.e. how the :cpp:`BoxArray` on which +:cpp:`MultiFabs` will be built is defined at each level. + +See :ref:`sec:load_balancing` for the strategies AMReX supports for distributing +grids to MPI ranks, i.e. defining the :cpp:`DistributionMapping` with which +:cpp:`MultiFabs` at that level will be built. + +We also note that we can create separate grids, and map them in different ways to MPI ranks, for +different types of data in a single calculation. We refer to this as the "dual grid approach" +and the most common usage is to load balance mesh and particle data separately. See :ref:`sec:dual_grid` +for more about this approach. + +When running on multicore machines with OpenMP, we can also control the distribution of +work by setting the size of grid tiles (by defining :cpp:`fabarray_mfiter.tile_size`), and if relevant, of +particle tiles (by defining :cpp:`particle.tile_size`). We can also specify the strategy for assigning +tiles to OpenMP threads. See :ref:`sec:basics:mfiter:tiling` for more about tiling. + +.. toctree:: + :maxdepth: 1 + + GridCreation + DualGrid + LoadBalancing diff --git a/Docs/sphinx_documentation/source/conf.py b/Docs/sphinx_documentation/source/conf.py new file mode 100644 index 0000000..32cff56 --- /dev/null +++ b/Docs/sphinx_documentation/source/conf.py @@ -0,0 +1,186 @@ +# -*- coding: utf-8 -*- +# +# amrex documentation build configuration file, created by +# sphinx-quickstart on Thu Oct 19 14:30:08 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +from datetime import datetime + +def get_amrex_version(): + today = datetime.today() + return u'%s.%.2d-dev' % (str(today.year)[-2:], (today.month + 1) % 12) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.mathjax', + 'sphinx.ext.githubpages', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx'] + +intersphinx_mapping = { + 'amrex_tutorials': ('https://amrex-codes.github.io/amrex/tutorials_html/', None), + 'amrex_hydro':('https://amrex-fluids.github.io/amrex-hydro/docs_html/', None) +} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['ytemplates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'amrex' +copyright = u'2024, AMReX Team' +author = u'AMReX Team' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = get_amrex_version() +# The full version, including alpha/beta/rc tags. +release = get_amrex_version() + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# 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 = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +numfig = True + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +html_css_files = [ + 'theme_overrides.css', # overrides for wide tables in RTD theme +] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + 'donate.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'amrexdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'amrex.tex', u'amrex Documentation', + u'AMReX Team', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'amrex', u'amrex Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'amrex', u'amrex Documentation', + author, 'amrex', 'One line description of project.', + 'Miscellaneous'), +] diff --git a/Docs/sphinx_documentation/source/index.rst b/Docs/sphinx_documentation/source/index.rst new file mode 100644 index 0000000..c86bbb1 --- /dev/null +++ b/Docs/sphinx_documentation/source/index.rst @@ -0,0 +1,80 @@ +.. _amrex_doc_indx: + +Welcome to AMReX's documentation +================================ + +AMReX is a software framework containing all the functionality to write +massively parallel, block-structured adaptive mesh refinement (AMR) +applications. AMReX is freely available `on Github +`_. + +AMReX is a project of the `High Performance Software Foundation (HPSF) +`_, which is part of the nonprofit `Linux Foundation +`_. + +All of AMReX's development is done in the GitHub repository under the +development branch; anyone can see the latest updates. A monthly release is tagged at the beginning +of each month. + +We are always happy to have users contribute to the AMReX source code. To +contribute, issue a pull request against the development branch (details `here +`_). Any level of +changes are welcomed: documentation, bug fixes, new test problems, new solvers, +etc. To obtain help, simply post a +`discussion `_ +or an `issue `_ +on the AMReX GitHub webpage. + +To learn AMReX there are walk-through guides and small stand-alone example codes that +demonstrate how to use different parts of the AMReX functionality. Extensive documentation +is available at `AMReX Guided Tutorials and Example Codes`_. + +.. _`AMReX Guided Tutorials and Example Codes`: https://amrex-codes.github.io/amrex/tutorials_html/ + +Besides this documentation, there is API documentation generated by `Doxygen +`_. + +Documentation on migration from BoxLib is available in the AMReX repository at Docs/Migration. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + Introduction + GettingStarted_Chapter + BuildingAMReX_Chapter + Basics_Chapter + ManagingGridHierarchy_Chapter + AmrCore_Chapter + AmrLevel_Chapter + ForkJoin + IO_Chapter + LinearSolvers_Chapter + Particle_Chapter + Fortran_Chapter + Python_Chapter + EB_Chapter + FFT_Chapter + TimeIntegration_Chapter + GPU_Chapter + Visualization_Chapter + Post_Processing_Chapter + Debugging + RuntimeParameters + AMReX_Profiling_Tools_Chapter + External_Profiling_Tools_Chapter + External_Frameworks_Chapter + Regression_Testing_Chapter + Faq + Governance + +.. toctree:: + :maxdepth: 1 + :caption: API + +The copyright notice of AMReX is included in the AMReX home directory +as README.md. +Your use of this software is under the 3-clause BSD license -- the license agreement is included in the +AMReX home directory as LICENSE. + +For a pdf version of this documentation, click :download:`here `. diff --git a/build_docs.sh b/build_docs.sh new file mode 100755 index 0000000..99acb75 --- /dev/null +++ b/build_docs.sh @@ -0,0 +1,15 @@ +#!/bin/bash +set -e # Exit with nonzero exit code if anything fails + +# Build sphinx +cd Docs/sphinx_documentation +echo "Build the Sphinx documentation for Amrex." +make PYTHON="python3" latexpdf +mv build/latex/amrex.pdf source/ +make clean +make SPHINXOPTS='-v -W --keep-going' PYTHON="python3" html +cd ../../ + +# copy sphinx to target location +cd build +cp -rp ../Docs/sphinx_documentation/build/html/* docs_html/