initial release

.gitignore

@@ -0,0 +1,20 @@
+# blacklist all
+/*
+# whitelist directories
+!/*
+# now whitelist stuff
+!.gitignore
+!**.py
+!README.md
+!*.cfg
+# blacklist
+build
+dist
+*.pyc
+*.pyo
+*.egg-info
+*/_git_rev.py
+doc/_build
+.vscode
+*.h5
+.pytest_cache

.readthedocs.yml

@@ -0,0 +1,21 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Non-HTML is useless until the docs are much longer
+formats: []
+
+python:
+  version: 3.6
+  install:
+    - method: setuptools
+      path: .
+    - requirements: doc/requirements.txt
+  system_packages: true

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Zachary J Weiner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.rst

@@ -0,0 +1,55 @@
+pystella: a distributed and accelerated framework for PDE solving
+=================================================================
+
+.. image:: https://readthedocs.org/projects/pystella/badge/?version=latest
+    :target: https://pystella.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+``pystella`` enables the easy expression of PDE systems and the algorithms to solve
+them in high-performance computing environments within Python.
+It provides interfaces to generate custom computational kernels
+via `loopy <http://mathema.tician.de/software/loopy>`_ which are executed
+on (multiple) CPUs or GPUs using
+`pyopencl <http://mathema.tician.de/software/pyopencl>`_
+and `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_.
+Moreover, ``pystella`` implements a number of algorithms for PDE time evolution
+and spatial discretization which can be readily applied to a variety of physical
+systems.
+
+Its features include:
+
+* code generation for performant element-wise kernels, stencil-based computations,
+  and reductions
+* distributed domain decomposition and grid boundary sychronization
+* time-stepping algorithms, including low-storage Runge-Kutta schemes
+* finite-difference and spectral-collocation methods for spatial derivatives
+* wrappers to OpenCL-based Fast Fourier Transforms (FFTs) and distributed,
+  CPU FFTs
+* methods for field analysis in Fourier space
+
+All of the above functionality is configured to run at high performance, as are
+the interfaces for generating custom kernels by default (though this is
+entirely user-configurable!).
+Additionally, the provided functionality is intended to work seamlessly whether
+running in distributed- (i.e., multiple devices) or shared-memory
+(i.e., a single device) contexts, without sacrificing performance in either case.
+
+``pystella`` was designed for lattice field theory simulations of *preheating* after
+cosmological inflation and provides functionality for the simple specification
+of physical models of this process (as well as computing the resulting gravitational
+wave emission).
+However, ``pystella`` is much more generic; these components can be viewed
+as examples for the symbolic representation of arbitrary physical systems as an
+interface to its code generation routines.
+Most systems discretized onto cartesian grids should be entirely within scope
+(e.g., lattice field theory, (magneto)hydrodynamics, Einstein's equations,
+electromagnetism, etc.).
+``pystella`` provides entrypoints at varying levels of abstraction---so if you like
+the idea of ``pystella`` but the algorithms you require are not implemented,
+you can create new interfaces (or extend existing ones) for your purposes
+with relative ease.
+(Better yet, consider contributing a PR!)
+
+``pystella`` is `fully documented <https://pystella.readthedocs.io/en/latest/>`_
+and is licensed under the liberal `MIT license
+<http://en.wikipedia.org/wiki/MIT_License>`_.

doc/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/_static/copybutton.js

@@ -0,0 +1,65 @@
+// Copyright 2014 PSF. Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+// File originates from the cpython source found in Doc/tools/sphinxext/static/copybutton.js
+
+$(document).ready(function() {
+    /* Add a [>>>] button on the top-right corner of code samples to hide
+     * the >>> and ... prompts and the output and thus make the code
+     * copyable. */
+    var div = $('.highlight-python .highlight,' +
+                '.highlight-default .highlight,' +
+                '.highlight-python3 .highlight')
+    var pre = div.find('pre');
+
+    // get the styles from the current theme
+    pre.parent().parent().css('position', 'relative');
+    var hide_text = 'Hide the prompts and output';
+    var show_text = 'Show the prompts and output';
+    var border_width = pre.css('border-top-width');
+    var border_style = pre.css('border-top-style');
+    var border_color = pre.css('border-top-color');
+    var button_styles = {
+        'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0',
+        'border-color': border_color, 'border-style': border_style,
+        'border-width': border_width, 'color': border_color, 'text-size': '75%',
+        'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em',
+        'border-radius': '0 3px 0 0'
+    }
+
+    // create and add the button to all the code blocks that contain >>>
+    div.each(function(index) {
+        var jthis = $(this);
+        if (jthis.find('.gp').length > 0) {
+            var button = $('<span class="copybutton">&gt;&gt;&gt;</span>');
+            button.css(button_styles)
+            button.attr('title', hide_text);
+            button.data('hidden', 'false');
+            jthis.prepend(button);
+        }
+        // tracebacks (.gt) contain bare text elements that need to be
+        // wrapped in a span to work with .nextUntil() (see later)
+        jthis.find('pre:has(.gt)').contents().filter(function() {
+            return ((this.nodeType == 3) && (this.data.trim().length > 0));
+        }).wrap('<span>');
+    });
+
+    // define the behavior of the button when it's clicked
+    $('.copybutton').click(function(e){
+        e.preventDefault();
+        var button = $(this);
+        if (button.data('hidden') === 'false') {
+            // hide the code output
+            button.parent().find('.go, .gp, .gt').hide();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
+            button.css('text-decoration', 'line-through');
+            button.attr('title', show_text);
+            button.data('hidden', 'true');
+        } else {
+            // show the code output
+            button.parent().find('.go, .gp, .gt').show();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
+            button.css('text-decoration', 'none');
+            button.attr('title', hide_text);
+            button.data('hidden', 'false');
+        }
+    });
+});

doc/changes.rst

@@ -0,0 +1,7 @@
+User-visible Changes
+====================
+
+Version 2019.5
+--------------
+
+* Initial release.

doc/citing.rst

@@ -0,0 +1,12 @@
+Citing pystella
+===============
+
+If you use :mod:`pystella` for your work, please cite the following pair of articles::
+
+    ..
+
+Here are Bibtex entries for your convenience::
+
+    @article{}
+
+    @article{}