diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 9e7bb1d39d0..f14d96eaf6c 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -7,31 +7,14 @@ on: jobs: build: - runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - name: Set up Python - uses: actions/setup-python@v4 - with: - # TODO: 3.x should be fine, but for now we enforce 3.10 to work around - # the "fatal error: longintrepr.h: No such file or directory" error - # triggered by revolve/cython in 3.11 - python-version: '3.10' - - name: Install Sphinx - run: | - python -m pip install --upgrade pip - pip install sphinx sphinx_rtd_theme - pip install -e . - - - name: Generate documentation - working-directory: docs - run: make html - - name: Deploy - uses: peaceiris/actions-gh-pages@v3 + - name: Repository Dispatch + uses: peter-evans/repository-dispatch@v2 with: - personal_token: ${{ secrets.PERSONAL_TOKEN }} - publish_branch: gh-pages - publish_dir: ./docs/_build/html + token: ${{ secrets.DEPLOY_DOC_PAT }} + repository: devitocodes/devitoproject.org + event-type: deploy-docs \ No newline at end of file diff --git a/FAQ.md b/FAQ.md index ace1b72b400..8cb99ace323 100644 --- a/FAQ.md +++ b/FAQ.md @@ -39,7 +39,7 @@ ## How can I see the code generated by Devito? After you build an ```op=Operator(...)``` implementing one or more equations, you can use ```print(op)``` to see the generated low level code. The example below builds an operator that takes a 1/2 cell forward shifted derivative of the ```Function``` **f** and puts the result in the ```Function``` **g**. -``` +```python import numpy as np import devito from devito import Grid, Function, Eq, Operator @@ -54,7 +54,7 @@ print(op) And the output: -``` +```C #define _POSIX_C_SOURCE 200809L #include "stdlib.h" #include "math.h" @@ -107,7 +107,8 @@ int Kernel(struct dataobj *restrict f_vec, struct dataobj *restrict g_vec, const Set the environment variable `DEVITO_LOGGING=DEBUG`. When an Operator gets compiled, the used compilation command will be emitted to stdout. If nothing seems to change, it is possible that no compilation is happening under-the-hood as all kernels have already been compiled in a previous run. You will then have to clear up the Devito kernel cache. From the Devito root directory, run: -``` + +```bash python scripts/clear_devito_cache.py ``` @@ -151,7 +152,8 @@ Take a look [here](https://github.com/devitocodes/devito/tree/master/examples/pe Devito applies several performance optimizations to improve the number of operations ("operation count") in complex expressions. These optimizations are designed to do a really good job but also be reasonably fast. One such pass attempts to factorize as many common terms as possible in expressions in order to reduce the operation count. We will construct a demonstrative example below that has a common term that is _not_ factored out by the Devito optimization. The difference in floating-point operations per output point for the factoring of that term is about 10 percent, and the generated C is different, but numerical outputs of running the two different operators are indistinguishable to machine precision. In terms of actual performance, the (few) missed factorization opportunities may not necessarily be a relevant issue: as long as the code is not heavily compute-bound, the runtimes may only be slightly higher than in the optimally-factorized version. #### Operator 1: -``` + +```python ux_update = t.spacing**2 * b * \ ((c33 * u_x.dx(x0=x+x.spacing/2)).dx(x0=x-x.spacing/2) + (c55 * u_x.dz(x0=z+z.spacing/2)).dz(x0=z-z.spacing/2) + @@ -162,8 +164,10 @@ stencil_x = Eq(u_x.forward, ux_update) print("\n", stencil_x) op = Operator([stencil_x]) ``` + #### Operator 2: -``` + +```python ux_update = \ t.spacing**2 * b * (c33 * u_x.dx(x0=x+x.spacing/2)).dx(x0=x-x.spacing/2) + \ t.spacing**2 * b * (c55 * u_x.dz(x0=z+z.spacing/2)).dz(x0=z-z.spacing/2) + \ @@ -176,7 +180,8 @@ op = Operator([stencil_x]) ``` #### Output 1: -``` + +```bash Eq(u_x(t + dt, x, z), dt**2*(Derivative(c13(x, z)*Derivative(u_z(t, x, z), z), x) + Derivative(c33(x, z)*Derivative(u_x(t, x, z), x), x) + Derivative(c55(x, z)*Derivative(u_x(t, x, z), z), z) + Derivative(c55(x, z)*Derivative(u_z(t, x, z), x), z))*b(x, z) + (-dt*wOverQ(x, z) + 2)*u_x(t, x, z) + (dt*wOverQ(x, z) - 1)*u_x(t - dt, x, z)) Operator `Kernel` generated in 1.26 s * lowering.Expressions: 0.61 s (48.7 %) @@ -186,7 +191,8 @@ Flops reduction after symbolic optimization: [1160 --> 136] ``` #### Output 2: -``` + +```bash Eq(u_x(t + dt, x, z), dt**2*b(x, z)*Derivative(c13(x, z)*Derivative(u_z(t, x, z), z), x) + dt**2*b(x, z)*Derivative(c33(x, z)*Derivative(u_x(t, x, z), x), x) + dt**2*b(x, z)*Derivative(c55(x, z)*Derivative(u_x(t, x, z), z), z) + dt**2*b(x, z)*Derivative(c55(x, z)*Derivative(u_z(t, x, z), x), z) + (-dt*wOverQ(x, z) + 2)*u_x(t, x, z) + (dt*wOverQ(x, z) - 1)*u_x(t - dt, x, z)) Operator `Kernel` generated in 1.12 s * lowering.Expressions: 0.59 s (53.0 %) @@ -221,7 +227,8 @@ You will note that this method uses placeholders for the material parameter arra ### How to get the list of Devito environment variables You can get the list of environment variables with the following python code: -``` + +```python from devito import print_defaults print_defaults() ``` @@ -304,7 +311,8 @@ Set `DEVITO_IGNORE_UNKNOWN_PARAMS=1` to avoid Devito raising an exception if one ## How do you run the unit tests from the command line In addition to the [tutorials]( https://www.devitoproject.org/devito/tutorials.html), the unit tests provide an excellent way to see how the Devito API works with small self-contained examples. You can exercise individual unit tests with the following python code: -``` + +```bash pytest pytest -vs [more detailed log] ``` @@ -315,7 +323,7 @@ pytest -vs [more detailed log] ## What is the difference between f() and f[] notation Devito offers a functional language to express finite difference operators. This is introduced [here](https://github.com/devitocodes/devito/blob/master/examples/userapi/01_dsl.ipynb) and systematically used throughout our examples and tutorials. The language relies on what in jargon we call the "f() notation". -``` +```python >>> from devito import Grid, Function >>> grid = Grid(shape=(5, 6)) >>> f = Function(name='f', grid=grid, space_order=2) @@ -327,7 +335,7 @@ Derivative(f(x, y), x) Sometimes, one wishes to escape the constraints of the language. Instead of taking derivatives, other special operations are required. Or perhaps, a specific grid point needs to be accessed. In such a case, one could use the "f[] notation" or "indexed notation". Following on from the example above: -``` +```python >>> x, y = grid.dimensions >>> f[x + 1000, y] f[x + 1000, y] @@ -335,7 +343,7 @@ f[x + 1000, y] The indexed object can be used at will to construct `Eq`s, and they can be mixed up with objects stemming from the "f() notation". -``` +```python >>> f.dx + f[x + 1000, y] Derivative(f(x, y), x) + f[x + 1000, y] ``` @@ -378,7 +386,8 @@ The indexed notation, or "f[] notation", is discussed [here](#What-is-the-differ ## What's up with object\.data The `.data` property which is associated with objects such as `Constant`, `Function` and `SparseFunction` (along with their derivatives) represents the 'numerical' value of the 'data' associated with that particular object. For example, a `Constant` will have a single numerical value associated with it as shown in the following snippet -``` + +```python from devito import Constant c = Constant(name='c') @@ -386,11 +395,14 @@ c.data = 2.7 print(c.data) ``` -``` + +```default 2.7 ``` + Then, a `Function` defined on a `Grid` will have a data value associated with each of the grid points (as shown in the snippet below) and so forth. -``` + +```python import numpy as np from devito import Grid, Function @@ -400,7 +412,8 @@ f.data[:] = np.arange(16).reshape(grid.shape) print(f.data) ``` -``` + +```default [[ 0. 1. 2. 3.] [ 4. 5. 6. 7.] [ 8. 9. 10. 11.] @@ -412,27 +425,36 @@ print(f.data) ## How do I create and N-dimensional grid Grids are often created via, e.g., -``` + +```python grid = Grid(shape=(5, 5)) ``` + where printing the `grid` object then returns: -``` + +```default Grid[extent=(1.0, 1.0), shape=(5, 5), dimensions=(x, y)] -``` -Here we see the `grid` has been created with the 'default' dimensions `x` and `y`. If a grid is created and passed a shape of `(5, 5, 5)` we'll see that in addition it has a `z` dimension. However, what if we want to create a grid with, say, a shape of `(5, 5, 5, 5)`? For this case, we've now run out of the dimensions defined by default and hence need to create our own dimensions to achieve this. This can be done via, e.g., ``` + +Here we see the `grid` has been created with the 'default' dimensions `x` and `y`. If a grid is created and passed a shape of `(5, 5, 5)` we'll see that in addition it has a `z` dimension. However, what if we want to create a grid with, say, a shape of `(5, 5, 5, 5)`? For this case, we've now run out of the dimensions defined by default and hence need to create our own dimensions to achieve this. This can be done via, e.g., + +```python a = SpaceDimension('a') b = SpaceDimension('b') c = SpaceDimension('c') d = SpaceDimension('d') grid = Grid(shape=(5, 5, 5, 5), dimensions=(a, b, c, d)) ``` + where now, printng `grid` we get -``` + +```default Grid[extent=(1.0, 1.0, 1.0, 1.0), shape=(5, 5, 5, 5), dimensions=(a, b, c, d)] ``` + and `grid.shape` returns -``` + +```default (5, 5, 5, 5) ``` @@ -463,7 +485,8 @@ Loop fission (to maximize parallelism) ## As time increases in the finite difference evolution, are wavefield arrays "swapped" as you might see in c/c++ code In c/c++ code using two wavefield arrays for second order acoustics, you might see code like the following to “swap” the wavefield arrays at each time step: -``` + +```C float *p_tmp = p_old; p_old = p_cur; p_cur = p_tmp; @@ -491,7 +514,7 @@ First, classes such as `Function` or `SparseTimeFunction` are inherently complex Second, you must know that these objects are subjected to so-called reconstruction during compilation. Objects are immutable inside Devito; therefore, even a straightforward symbolic transformation such as `f[x] -> f[y]` boils down to performing a reconstruction, that is, creating a whole new object. Since `f` carries around several attributes (e.g., shape, grid, dimensions), each time Devito performs a reconstruction, we only want to specify which attributes are changing -- not all of them, as it would make the code ugly and incredibly complicated. The solution to this problem is that all the base symbolic types inherit from a common base class called `Reconstructable`; a `Reconstructable` object has two special class attributes, called `__rargs__` and `__rkwargs__`. If a subclass adds a new positional or keyword argument to its `__init_finalize__`, it must also be added to `__rargs__` or `__rkwargs__`, respectively. This will provide Devito with enough information to perform a reconstruction when it's needed during compilation. The following example should clarify: -``` +```python class Foo(Reconstructable): __rargs__ = ('a', 'b') __rkwargs__ = ('c',) @@ -515,7 +538,7 @@ class Bar(Foo): You are unlikely to care about how reconstruction works in practice, but here are a few examples for `a = Foo(3, 5)` to give you more context. -``` +```python a._rebuild() -> "x(3, 5, 4)" (i.e., copy of `a`). a._rebuild(4) -> "x(4, 5, 4)" a._rebuild(4, 7) -> "x(4, 7, 4)" @@ -534,7 +557,7 @@ There is currently no API to achieve this straightforwardly. However, there are * via env vars: use a [CustomCompiler](https://github.com/opesci/devito/blob/v4.0/devito/compiler.py#L446) -- just leave the `DEVITO_ARCH` environment variable unset or set it to `'custom'`. Then, `export CFLAGS="..."` to tell Devito to use the exported flags in place of the default ones. * programmatically: subclass one of the compiler classes and set `self.cflags` to whatever you need. Do not forget to add the subclass to the [compiler registry](https://github.com/opesci/devito/blob/v4.0/devito/compiler.py#L472). For example, you could do -``` +```python from devito import configuration, compiler_registry from devito.compiler import GNUCompiler @@ -576,7 +599,8 @@ Until Devito v3.5 included, domain decomposition occurs along the fastest axis. ## How should I use MPI on multi-socket machines In general you should use one MPI rank per NUMA node on a multi-socket machine. You can find the number of numa nodes with the `lscpu` command. For example, here is the relevant part of the output from the `lscpu` command on an AMD 7502 2 socket machine with 2 NUMA nodes: -``` + +```default Architecture: x86_64 CPU(s): 64 On-line CPU(s) list: 0-63 @@ -597,7 +621,7 @@ NUMA node1 CPU(s): 32-63 There are a few things you may want to check * To refer to the actual ("global") shape of the domain, you should always use `grid.shape` (or analogously through a `Function`, `f.grid.shape`). And unless you know well what you're doing, you should never use the function shape, namely `f.shape` or `f.data.shape`, as that will return the "local" domain shape, that is the data shape after domain decomposition, which might differ across the various MPI ranks. -* <... to be completed ...> + [top](#Frequently-Asked-Questions) @@ -613,17 +637,23 @@ This is likely due to an out-of-bounds (OOB) array access while running the gene ## Can I manually modify the C code generated by Devito and test these modifications Yes, as of Devito v3.5 it is possible to modify the generated C code and run it inside Devito. First you need to get the C file generated for a given `Operator`. Run your code in `DEBUG` mode: -``` + +```bash DEVITO_LOGGING=DEBUG python your_code.py ``` + The generated code path will be shown as in the excerpt below: -``` + +```default CustomCompiler: compiled `/tmp/devito-jitcache-uid1000/ed41e9373af1bc129471b7ae45e1c3740b60a856.c` [0.29 s] ``` + You can now open the C file, do the modifications you like, and save them. Finally, rerun the same program but this time with the _Devito JIT backdoor_ enabled: -``` + +```bash DEVITO_JIT_BACKDOOR=1 python your_code.py ``` + This will force Devito to recompile and link the modified C code. If you have a large codebase with many `Operator`s, here's a [trick](https://github.com/devitocodes/devito/wiki/Efficient-use-of-DEVITO_JIT_BACKDOOR-in-large-codes-with-many-Operators) to speed up your hacking with the JIT backdoor. @@ -675,7 +705,7 @@ About the GPts/s metric, that is number of gigapoints per seconds. The "points" An excerpt of the performance profile emitted by Devito upon running an Operator is provided below. In this case, the Operator has two sections, ``section0`` and ``section1``, and ``section1`` consists of two consecutive 6D iteration spaces whose size is given between angle brackets. -``` +```default Global performance: [OI=0.16, 8.00 GFlops/s, 0.04 GPts/s] Local performance: * section0<136,136,136> run in 0.10 s [OI=0.16, 0.14 GFlops/s] @@ -695,7 +725,7 @@ The floating-point operations are counted once all of the symbolic flop-reducing To calculate the GFlops/s performance, Devito multiplies the floating-point operations calculated at compile time by the size of the iteration space, and it does that at the granularity of individual expressions. For example, consider the following snippet: -``` +```default for x = x_m to x_M for y = y_m to y_M diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index f830cd685c1..00000000000 --- a/docs/Makefile +++ /dev/null @@ -1,225 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " epub3 to make an epub3" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - @echo " dummy to check syntax errors of document sources" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Devito.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Devito.qhc" - -.PHONY: applehelp -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Devito" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Devito" - @echo "# devhelp" - -.PHONY: epub -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: epub3 -epub3: - $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 - @echo - @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." - -.PHONY: latex -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexpdf -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: latexpdfja -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -.PHONY: gettext -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -.PHONY: dummy -dummy: - $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy - @echo - @echo "Build finished. Dummy builder generates no files." diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 1576fc85dbd..00000000000 --- a/docs/make.bat +++ /dev/null @@ -1,281 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -set I18NSPHINXOPTS=%SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. epub3 to make an epub3 - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. xml to make Docutils-native XML files - echo. pseudoxml to make pseudoxml-XML files for display purposes - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - echo. coverage to run coverage check of the documentation if enabled - echo. dummy to check syntax errors of document sources - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - - -REM Check if sphinx-build is available and fallback to Python version if any -%SPHINXBUILD% 1>NUL 2>NUL -if errorlevel 9009 goto sphinx_python -goto sphinx_ok - -:sphinx_python - -set SPHINXBUILD=python -m sphinx.__init__ -%SPHINXBUILD% 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.http://sphinx-doc.org/ - exit /b 1 -) - -:sphinx_ok - - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Devito.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Devito.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "epub3" ( - %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3 - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub3 file is in %BUILDDIR%/epub3. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -if "%1" == "coverage" ( - %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 - echo. - echo.Testing of coverage in the sources finished, look at the ^ -results in %BUILDDIR%/coverage/python.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -if "%1" == "dummy" ( - %SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. Dummy builder generates no files. - goto end -) - -:end diff --git a/docs/source/_static/devito_logo.png b/docs/source/_static/devito_logo.png deleted file mode 100644 index 1e1192841e9..00000000000 Binary files a/docs/source/_static/devito_logo.png and /dev/null differ diff --git a/docs/source/_static/devito_style.css b/docs/source/_static/devito_style.css deleted file mode 100644 index 07b588ed2c7..00000000000 --- a/docs/source/_static/devito_style.css +++ /dev/null @@ -1,75 +0,0 @@ -/* Width of the main tab -.wy-nav-content { - max-width: none; -} -*/ - -/* Sidebar header (and topbar for mobile) */ -.wy-side-nav-search, .wy-nav-top { - background: #e5e5e5; -} - -/* Sidebar -.wy-nav-side { - background: #ff0000; -} -*/ - -/* Link colors */ -a:link { - color: #54c6a4; -} -a:hover, a:visited, a:active { - color: #1ea47d; -} - -a.icon { - color: #343131; -} - -.wy-side-nav-search > div.version { - color: #343131; -} - -.rst-content dl:not(.docutils) dt { - color: #404040; -} - -.rst-content dl:not(.docutils) dt { - border-top: solid 3px #54c6a4; - background: #dff1ec; -} - -/* To get rid of colored boxes around methods -.rst-content dl:not(.docutils) dl dt { - border-left: none; - background: none; -} -*/ - -/* Make sure the colored box around classes takes up the whole page width */ -.rst-content dl:not(.docutils) dt { - display: block; -} - -/* A thin line right below Examples, Notes, ... */ -p.rubric { - border-bottom: 1px solid rgb(204, 204, 204); -} - -/* A vertical line on the left of Parameters */ -.wy-table, .rst-content table.docutils, .rst-content table.field-list { - border-left: 5px solid rgb(238, 238, 238) !important; -} - -/* A grey box in background for Parameters */ -.rst-content table.field-list .field-name { - display: inline-block; - background-color: rgb(238, 238, 238); - padding: 1px 8px 1px 5px; -} - -/* Put class/method parameters closer to the "Parameters" box */ -.wy-table td, .rst-content table.docutils td, .rst-content table.field-list td, .wy-table th, .rst-content table.docutils th, .rst-content table.field-list th { - padding: 2px 0px 2px 0px; -} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html deleted file mode 100644 index f76b65b8ad7..00000000000 --- a/docs/source/_templates/layout.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "!layout.html" %} -{% block extrahead %} - -{% endblock %} diff --git a/docs/source/builtins.rst b/docs/source/builtins.rst deleted file mode 100644 index dac4db2f96b..00000000000 --- a/docs/source/builtins.rst +++ /dev/null @@ -1,12 +0,0 @@ -================== -Built-in Operators -================== - -Devito provides a number of convenience Operators that can be imported and run -in user code to facilitate development. These are exposed as free functions. - -All built-in Operators support MPI. - -.. automodule:: devito.builtins - :members: - :show-inheritance: diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 3aa28eb90fd..00000000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,430 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Devito documentation build configuration file, created by -# sphinx-quickstart on Wed Jul 20 13:02:08 2016. -# -# 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('.')) - -# -- 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.autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'sphinx.ext.githubpages', - 'sphinx.ext.mathjax', - 'sphinx.ext.napoleon' # support for numpydoc -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The encoding of source files. -# -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Devito v4.6.2' -copyright = u'2016-2019, Devito' -author = u'The Devito Community' - -# 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 = u'4.6.2' -# The full version, including alpha/beta/rc tags. -# release = u'4.6.2' - -# 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' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# -# today = '' -# -# Else, today_fmt is used as the format for a strftime call. -# -# today_fmt = '%B %d, %Y' - -# 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 = ['_build', 'Thumbs.db', '.DS_Store'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -# -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = 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 themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. -# " v documentation" by default. -# -html_title = u'Devito v4.6.2' - -# A shorter title for the navigation bar. Default is the same as html_title. -# -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# -html_logo = '_static/devito_logo.png' - -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# -html_favicon = '_static/devito_logo.png' - -# 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'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# -# html_extra_path = [] - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -# html_last_updated_fmt = None - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# -# html_additional_pages = {} - -# If false, no module index is generated. -# -# html_domain_indices = True - -# If false, no index is generated. -# -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# -html_show_sphinx = False - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' -# -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# -# html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Devitodoc' - -# -- 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, 'Devito.tex', u'Devito Documentation', - u'Devito', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# -# latex_use_parts = False - -# If true, show page references after internal links. -# -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# -# latex_appendices = [] - -# It false, will not define \strong, \code, itleref, \crossref ... but only -# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added -# packages. -# -# latex_keep_old_macro_names = True - -# If false, no module index is generated. -# -# latex_domain_indices = True - - -# -- 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, 'devito', u'Devito Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -# -# man_show_urls = False - - -# -- 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, 'Devito', u'Devito Documentation', - author, 'Devito', u'Devito Documentation.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -# -# texinfo_appendices = [] - -# If false, no module index is generated. -# -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# -# texinfo_no_detailmenu = False - - -# -- Options for Epub output ---------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = copyright - -# The basename for the epub file. It defaults to the project name. -# epub_basename = project - -# The HTML theme for the epub output. Since the default themes are not -# optimized for small screen space, using the same theme for HTML and epub -# output is usually not wise. This defaults to 'epub', a theme designed to save -# visual space. -# -# epub_theme = 'epub' - -# The language of the text. It defaults to the language option -# or 'en' if the language is not set. -# -# epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -# epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -# -# epub_cover = () - -# A sequence of (type, uri, title) tuples for the guide element of content.opf. -# -# epub_guide = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -# -# epub_pre_files = [] - -# HTML files that should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -# -# epub_post_files = [] - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - -# The depth of the table of contents in toc.ncx. -# -# epub_tocdepth = 3 - -# Allow duplicate toc entries. -# -# epub_tocdup = True - -# Choose between 'default' and 'includehidden'. -# -# epub_tocscope = 'default' - -# Fix unsupported image types using the Pillow. -# -# epub_fix_images = False - -# Scale large images. -# -# epub_max_image_width = 0 - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# -# epub_show_urls = 'inline' - -# If false, no index is generated. -# -# epub_use_index = True diff --git a/docs/source/constant.rst b/docs/source/constant.rst deleted file mode 100644 index cd6e9510ce5..00000000000 --- a/docs/source/constant.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Constant -======== - -.. autoclass:: devito.types.Constant - :members: - :show-inheritance: diff --git a/docs/source/dimension.rst b/docs/source/dimension.rst deleted file mode 100644 index 459c738853b..00000000000 --- a/docs/source/dimension.rst +++ /dev/null @@ -1,7 +0,0 @@ -========= -Dimension -========= - -.. automodule:: devito.types.dimension - :members: - :show-inheritance: diff --git a/docs/source/download.rst b/docs/source/download.rst deleted file mode 100644 index 2ee073f69bf..00000000000 --- a/docs/source/download.rst +++ /dev/null @@ -1,132 +0,0 @@ -=========================== -Download and Install Devito -=========================== - -There are two main approaches to installing Devito. - -- `Docker`_, for those looking for the least-friction way to try Devito -- `Virtual environment`_, for those looking to use Devito as part of a project alongside other packages - -Docker ------- - -For detailed installation instructions and information on the Devito Docker image library please follow -the docker/README.md_ - -.. _README.md: https://github.com/devitocodes/devito/tree/master/docker#readme - - -Virtual environment -------------------- - -venv route -`````````` - -Devito is available as a `pip package`_ in PyPI. - -Create a `Python virtual environment`_ - -.. _Python virtual environment: https://docs.python.org/3/library/venv.html - -.. code-block:: shell - - python3 -m venv - -Source the newly created `venv`. This needs to be repeated each time a new terminal is open. - -.. code-block:: shell - - source /bin/activate - - -To install the `latest Devito release`_ along with any additional dependencies, follow: - -.. code-block:: shell - - pip install devito - # ...or to install additional dependencies: - # pip install devito[extras,mpi,nvidia,tests] - -.. _latest Devito release: https://pypi.org/project/devito/#history - -To install the latest Devito development version, without the tutorials, follow: - -.. code-block:: shell - - pip install git+https://github.com/devitocodes/devito.git - # ...or to install additional dependencies: - # pip install git+https://github.com/devitocodes/devito.git#egg=project[extras,mpi,nvidia,tests] - -Additional dependencies: - -- extras : optional dependencies for Jupyter notebooks, plotting, benchmarking -- tests : optional dependencies required for testing infrastructure -- mpi : optional dependencies for MPI (mpi4py) -- nvidia : optional dependencies for targetting GPU deployment - -.. _pip package: https://pypi.org/project/devito/ - -Note that here, you do not need to get the code via `git clone`. -Depending on your needs, this might also be the recommended setup for using Devito -in a production-like environment. However, since some components need to be -compiled before use, this approach may be sensitive to the C/C++ compilers present -on your system and the related environment, including what other packages you might -have installed. - - -conda route -``````````` -Please install either Anaconda_ or Miniconda_. - -.. _Anaconda: https://www.continuum.io/downloads - -.. _Miniconda: https://conda.io/miniconda.html - -.. _Python virtual environment: https://docs.python.org/3/library/venv.html - -.. _Conda environment: https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html - -.. code-block:: shell - - # Create new env with the name devito - conda create --name devito - # Activate the environment - conda activate devito - -and finally, install Devito along with any extra dependencies: - -.. code-block:: shell - - pip install devito - # ... or to install additional dependencies - # pip install devito[extras,mpi,nvidia,tests] - - -For developers -`````````````` -First clone Devito: - -.. code-block:: shell - - git clone https://github.com/devitocodes/devito.git - cd devito - -and then install the requirements in your virtual environment (venv or conda): - -.. code-block:: shell - - # Install requirements - pip install -e . - # ...or to install additional dependencies - # pip install -e .[extras,mpi,nvidia,tests] - - -Facing issues? --------------- - -If you are facing any issues, we are happy to help on Slack_. Also, have a look at our -list of known installation issues_. - -.. _issues: https://github.com/devitocodes/devito/wiki/Installation-Issues - -.. _Slack: https://join.slack.com/t/devitocodes/shared_invite/zt-gtd2yxj9-Y31YKk_7lr9AwfXeL2iMFg diff --git a/docs/source/equation.rst b/docs/source/equation.rst deleted file mode 100644 index 4668048a4fa..00000000000 --- a/docs/source/equation.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Equation -======== - -.. automodule:: devito.types.equation - :members: - :show-inheritance: diff --git a/docs/source/finite-difference.rst b/docs/source/finite-difference.rst deleted file mode 100644 index 2be32e1756f..00000000000 --- a/docs/source/finite-difference.rst +++ /dev/null @@ -1,6 +0,0 @@ -================================ -Finite-difference approximations -================================ - -.. automodule:: devito.finite_differences.finite_difference - :members: diff --git a/docs/source/function.rst b/docs/source/function.rst deleted file mode 100644 index 98ba2de5a91..00000000000 --- a/docs/source/function.rst +++ /dev/null @@ -1,9 +0,0 @@ -======== -Function -======== - -.. Need to explicitly state each member to avoid showing sympy members - -.. autoclass:: devito.types.Function - :members: name, dtype, grid, dimensions, space_dimensions, shape, shape_with_halo, shape_allocated, shape_global, data, data_domain, data_with_halo, data_ro_domain, data_ro_with_halo, space_order, sum, avg - :show-inheritance: diff --git a/docs/source/grid.rst b/docs/source/grid.rst deleted file mode 100644 index e8c6b67fd42..00000000000 --- a/docs/source/grid.rst +++ /dev/null @@ -1,7 +0,0 @@ -==== -Grid -==== - -.. autoclass:: devito.types.Grid - :members: - :show-inheritance: diff --git a/docs/source/grids.rst b/docs/source/grids.rst deleted file mode 100644 index 5d653e1dd41..00000000000 --- a/docs/source/grids.rst +++ /dev/null @@ -1,8 +0,0 @@ -===== -Grids -===== - -.. toctree:: - - grid - subdomain diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index b52eefde856..00000000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. Devito documentation master file, created by - sphinx-quickstart on Wed Jul 20 13:02:08 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Devito -====== - -Welcome to the Devito documentation! - -`Devito `_ is a software to -implement optimised finite difference (FD) computation from -high-level symbolic problem definitions. Starting from symbolic -equations defined in `SymPy `_, -Devito employs automated code generation and just-in-time (JIT) -compilation to execute FD kernels on multiple computer platforms. - -Getting started ---------------- - -You can get instructions on how to download and install Devito -:doc:`here `. - -To learn how to use Devito, check our :doc:`tutorials and examples `. -Here you will also find documentation about the inner workings of the compiler. - -You can find the API Reference, which includes detailed explanations and -inline examples, :doc:`here `. - -.. title:: The Devito project - -.. toctree:: - :hidden: - - Download - Tutorials - FAQ - API Reference diff --git a/docs/source/operator.rst b/docs/source/operator.rst deleted file mode 100644 index 909be6b8c6b..00000000000 --- a/docs/source/operator.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Operator -======== - -.. automodule:: devito.operator.operator - :members: - :undoc-members: diff --git a/docs/source/precsparsefunction.rst b/docs/source/precsparsefunction.rst deleted file mode 100644 index 0058ca2f649..00000000000 --- a/docs/source/precsparsefunction.rst +++ /dev/null @@ -1,7 +0,0 @@ -========================= -PrecomputedSparseFunction -========================= - -.. autoclass:: devito.types.PrecomputedSparseFunction - :members: name, dtype, grid, dimensions, shape, data, data_domain, data_with_halo, data_ro_domain, data_ro_with_halo, space_order, gridpoints, inject, interpolate - :show-inheritance: diff --git a/docs/source/precsparsetimefunction.rst b/docs/source/precsparsetimefunction.rst deleted file mode 100644 index fb26782dcd5..00000000000 --- a/docs/source/precsparsetimefunction.rst +++ /dev/null @@ -1,7 +0,0 @@ -============================= -PrecomputedSparseTimeFunction -============================= - -.. autoclass:: devito.types.PrecomputedSparseTimeFunction - :members: name, dtype, grid, dimensions, shape, data, data_domain, data_with_halo, data_ro_domain, data_ro_with_halo, space_order, gridpoints, inject, interpolate, time_order - :show-inheritance: diff --git a/docs/source/sparsefunction.rst b/docs/source/sparsefunction.rst deleted file mode 100644 index cce3876ffd7..00000000000 --- a/docs/source/sparsefunction.rst +++ /dev/null @@ -1,7 +0,0 @@ -============== -SparseFunction -============== - -.. autoclass:: devito.types.SparseFunction - :members: name, dtype, grid, dimensions, shape, data, data_domain, data_with_halo, data_ro_domain, data_ro_with_halo, space_order, gridpoints, guard, inject, interpolate - :show-inheritance: diff --git a/docs/source/sparsetimefunction.rst b/docs/source/sparsetimefunction.rst deleted file mode 100644 index 66aa2c49eb3..00000000000 --- a/docs/source/sparsetimefunction.rst +++ /dev/null @@ -1,7 +0,0 @@ -================== -SparseTimeFunction -================== - -.. autoclass:: devito.types.SparseTimeFunction - :members: name, dtype, grid, dimensions, shape, data, data_domain, data_with_halo, data_ro_domain, data_ro_with_halo, space_order, gridpoints, guard, inject, interpolate, time_order - :show-inheritance: diff --git a/docs/source/subdomain.rst b/docs/source/subdomain.rst deleted file mode 100644 index dee2c03b0ac..00000000000 --- a/docs/source/subdomain.rst +++ /dev/null @@ -1,7 +0,0 @@ -========= -SubDomain -========= - -.. autoclass:: devito.types.SubDomain - :members: - :show-inheritance: diff --git a/docs/source/symbolic.rst b/docs/source/symbolic.rst deleted file mode 100644 index ffee006acd1..00000000000 --- a/docs/source/symbolic.rst +++ /dev/null @@ -1,18 +0,0 @@ -================ -Symbolic Objects -================ - -.. toctree:: - - dimension - constant - function - timefunction - sparsefunction - sparsetimefunction - precsparsefunction - precsparsetimefunction - vectorfunction - vectortimefunction - tensorfunction - tensortimefunction \ No newline at end of file diff --git a/docs/source/tensorfunction.rst b/docs/source/tensorfunction.rst deleted file mode 100644 index d473d278bff..00000000000 --- a/docs/source/tensorfunction.rst +++ /dev/null @@ -1,9 +0,0 @@ -======== -TensorFunction -======== - -.. Need to explicitly state each member to avoid showing sympy members - -.. autoclass:: devito.types.TensorFunction - :members: grid, space_dimensions, space_order, is_diagonal, is_symmetric, mat - :show-inheritance: \ No newline at end of file diff --git a/docs/source/tensortimefunction.rst b/docs/source/tensortimefunction.rst deleted file mode 100644 index 60f847a42bb..00000000000 --- a/docs/source/tensortimefunction.rst +++ /dev/null @@ -1,9 +0,0 @@ -======== -TensorTimeFunction -======== - -.. Need to explicitly state each member to avoid showing sympy members - -.. autoclass:: devito.types.TensorTimeFunction - :members: grid, space_dimensions, space_order, is_diagonal, is_symmetric, mat - :show-inheritance: \ No newline at end of file diff --git a/docs/source/timefunction.rst b/docs/source/timefunction.rst deleted file mode 100644 index 24655ea5d58..00000000000 --- a/docs/source/timefunction.rst +++ /dev/null @@ -1,9 +0,0 @@ -============ -TimeFunction -============ - -.. Need to explicitly state each member to avoid showing sympy members - -.. autoclass:: devito.types.TimeFunction - :members: name, dtype, grid, dimensions, space_dimensions, shape, shape_with_halo, shape_allocated, shape_global, data, data_domain, data_with_halo, data_ro_domain, data_ro_with_halo, space_order, sum, avg, time_order, backward, forward - :show-inheritance: diff --git a/docs/source/userapi.rst b/docs/source/userapi.rst deleted file mode 100644 index 5a2f20d5f65..00000000000 --- a/docs/source/userapi.rst +++ /dev/null @@ -1,12 +0,0 @@ -============= -API Reference -============= - -.. toctree:: - - grids - symbolic - finite-difference - equation - operator - builtins diff --git a/docs/source/vectorfunction.rst b/docs/source/vectorfunction.rst deleted file mode 100644 index a9f732ccbc0..00000000000 --- a/docs/source/vectorfunction.rst +++ /dev/null @@ -1,9 +0,0 @@ -======== -VectorFunction -======== - -.. Need to explicitly state each member to avoid showing sympy members - -.. autoclass:: devito.types.VectorFunction - :members: grid, space_dimensions, space_order, mat - :show-inheritance: \ No newline at end of file diff --git a/docs/source/vectortimefunction.rst b/docs/source/vectortimefunction.rst deleted file mode 100644 index 8c84929947b..00000000000 --- a/docs/source/vectortimefunction.rst +++ /dev/null @@ -1,9 +0,0 @@ -======== -VectorTimeFunction -======== - -.. Need to explicitly state each member to avoid showing sympy members - -.. autoclass:: devito.types.VectorTimeFunction - :members: grid, space_dimensions, space_order, mat - :show-inheritance: \ No newline at end of file