Merge pull request #3 from jan-david-fischbach/build-system

Build System: Pre-Commit, Docs and PyPi

.bumpversion.cfg

@@ -0,0 +1,10 @@
+[bumpversion]
+current_version = 0.2.0
+commit = True
+tag = True
+
+[bumpversion:file:./pyproject.toml]
+
+[bumpversion:file:./README.md]
+
+[bumpversion:file:jaxwell/__init__.py]

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

.github/workflows/pages.yml

@@ -0,0 +1,47 @@
+name: Sphinx docs to gh-pages
+
+on:
+  push:
+    branches:
+      - main
+      - build-system
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    name: Sphinx docs to gh-pages
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+      - name: Installing the library
+        shell: bash -l {0}
+        run: |
+          make dev
+      - name: make docs
+        run: |
+          make docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: "./docs/_build/html/"
+  deploy-docs:
+    needs: build-docs
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release PyPI
+
+on:
+  push:
+    tags: "v*"
+
+jobs:
+  release_pypi:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+          cache-dependency-path: pyproject.toml
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools wheel twine
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          make build
+          twine upload dist/*

.github/workflows/test_code.yml

@@ -0,0 +1,83 @@
+name: Test pre-commit, code and docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+      - name: Test pre-commit hooks
+        run: |
+          python -m pip install --upgrade pip
+          pip install pre-commit
+          pre-commit run -a
+  test_code:
+    needs: [pre-commit]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      max-parallel: 12
+      matrix:
+        python-version: ["3.10"]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+      - name: Install dependencies
+        run: |
+          pip install -e .[tests]
+      - name: Test with pytest
+        run: pytest
+  test_code_coverage:
+    runs-on: ubuntu-latest
+    needs: [pre-commit]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: |
+          pip install -e .[tests]
+      - name: Test with pytest
+        run: |
+          pytest --cov=jaxwell tests
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+  test_docs:
+    runs-on: ubuntu-latest
+    needs: [pre-commit]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+      - name: Install dependencies
+        run: |
+          make dev
+      - name: Test documentation
+        run: |
+          make docs

.gitignore

@@ -2,4 +2,5 @@
 build
 jaxwell.egg-info
 venv
-*__pycache__
+*__pycache__
+docs/_build

.pre-commit-config.yaml

@@ -0,0 +1,57 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "9260cbc9c84c06022993bfbcc42fdbf0305c5b8e"
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: name-tests-test
+        args: ["--pytest-test-first"]
+      - id: trailing-whitespace
+
+  - repo: https://github.com/psf/black
+    rev: "d9b8a6407e2f46304a8d36b18e4a73d8e0613519"
+    hooks:
+      - id: black
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: ddb39ad37166dbc938d853cc77606526a0b1622a
+    hooks:
+      - id: pyupgrade
+        args: [--py37-plus, --keep-runtime-typing]
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: 953faa6870f6663ac0121ab4a800f1ce76bca31f
+    hooks:
+      - id: shellcheck
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: fe1361fdcc274850d4099885a802f2c9f28aca08
+    hooks:
+      - id: bandit
+        args: [--exit-zero]
+        # ignore all tests, not just tests data
+        exclude: ^tests/
+
+  # - repo: https://github.com/pre-commit/mirrors-mypy
+  #   rev: "v1.0.1"
+  #   hooks:
+  #     - id: mypy
+  #       exclude: ^(docs/|example-plugin/|tests/fixtures)
+  #       additional_dependencies:
+  #         - "pydantic"
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: "6a0ba1854991b693612486cc84a2254de82d071d"
+    hooks:
+      - id: ruff
+
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.3.9
+    hooks:
+      - id: nbstripout

Makefile

@@ -0,0 +1,45 @@
+
+install:
+	pip install -e .[dev]
+	pre-commit install
+
+dev:
+	pip install -e .[dev,docs]
+
+test:
+	pytest -s
+
+cov:
+	pytest --cov=jaxwell
+
+mypy:
+	mypy . --ignore-missing-imports
+
+pylint:
+	pylint jaxwell
+
+ruff:
+	ruff --fix jaxwell/*.py
+
+git-rm-merged:
+	git branch -D `git branch --merged | grep -v \* | xargs`
+
+update:
+	pur
+
+update-pre:
+	pre-commit autoupdate --bleeding-edge
+
+release:
+	git push
+	git push origin --tags
+
+build:
+	rm -rf dist
+	pip install build
+	python -m build
+
+docs:
+	jb build docs
+
+.PHONY: docs

README.md

@@ -22,7 +22,7 @@ for the electric field `E` via the API
 x, err = jaxwell.solve(params, z, b)
 ```
 
-where `E → x`, `ω²ε → z`, `-iωJ → b`, 
+where `E → x`, `ω²ε → z`, `-iωJ → b`,
 `params` controls how the solve proceeds iteratively, and
 `err` is the error in the solution.
 
@@ -32,13 +32,11 @@ assumes `μ = 1` everywhere,
 and implements stretched-coordinate perfectly matched layers (SC-PML)
 for absorbing boundary conditions.
 
-You can install Jaxwell with `pip install git+https://github.com/jan-david-fischbach/jaxwell.git` 
-but the easiest way to get started is to go straight to the example 
+You can install Jaxwell with `pip install git+https://github.com/jan-david-fischbach/jaxwell.git`
+but the easiest way to get started is to go straight to the example
 [colaboratory notebook](https://colab.research.google.com/github/jan-david-fischbach/jaxwell/blob/main/example/colab.ipynb).
 
 References:
 
 - PMLs and diagonalization: [Shin2012] W. Shin and S. Fan. “Choice of the perfectly matched layer boundary condition for frequency-domain Maxwell's equations solvers.” Journal of Computational Physics 231 (2012): 3406–31
 - COCG algorithm: [Gu2014] X. Gu, T. Huang, L. Li, H. Li, T. Sogabe and M. Clemens, "Quasi-Minimal Residual Variants of the COCG and COCR Methods for Complex Symmetric Linear Systems in Electromagnetic Simulations," in IEEE Transactions on Microwave Theory and Techniques, vol. 62, no. 12, pp. 2859-2867, Dec. 2014
-
-

docs/_config.yml

@@ -0,0 +1,57 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: jaxwell
+author: Jan David Fischbach
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: cache
+  timeout: -1
+  allow_errors: true
+  # execute_notebooks: force
+  # execute_notebooks: "off"
+  # exclude_patterns:
+  #   - '*notebooks/devsim/01_pin_waveguide*'
+
+latex:
+  latex_engine: pdflatex # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
+  use_jupyterbook_latex: true # use sphinx-jupyterbook-latex for pdf builds as default
+
+# Add a bibtex file so that we can create citations
+
+html:
+  home_page_in_navbar: true
+  use_edit_page_button: true
+  use_repository_button: true
+  use_issues_button: true
+  baseurl: https://github.com/jan-david-fischbach/jaxwell
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/jan-david-fischbach/jaxwell
+  path_to_book: docs # Optional path to your book, relative to the repository root
+  branch: main # Which branch of the repository should be used when creating links (optional)
+
+launch_buttons:
+  notebook_interface: jupyterlab
+  colab_url: "https://colab.research.google.com"
+
+sphinx:
+  extra_extensions:
+    - "sphinx.ext.autodoc"
+    - "sphinx.ext.autodoc.typehints"
+    - "sphinx.ext.autosummary"
+    - "sphinx.ext.napoleon"
+    - "sphinx.ext.viewcode"
+    - "matplotlib.sphinxext.plot_directive"
+  config:
+    #autodoc_typehints: description
+    autodoc_type_aliases:
+      "ComponentSpec": "ComponentSpec"
+    nb_execution_show_tb: True
+    nb_custom_formats:
+        .py:
+            - jupytext.reads
+            - fmt: py

docs/_toc.yml

@@ -0,0 +1,9 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: index
+chapters:
+  - file: colab
+  - file: api
+  - file: changelog

docs/api.rst

@@ -0,0 +1,5 @@
+API
+===================================
+
+.. automodule:: jaxwell
+    :members: