Improve readme.

tbenthompson · Apr 5, 2021 · a9ea7a9 · a9ea7a9
2 parents fc7d89a + 0ec3758
commit a9ea7a9
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 55 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,3 @@
-# cutde
-
 <p align=center>
     <a target="_blank" href="https://www.python.org/downloads/" title="Python version"><img src="https://img.shields.io/badge/python-%3E=_3.6-green.svg"></a>
     <a target="_blank" href="https://pypi.org/project/cutde/" title="PyPI version"><img src="https://img.shields.io/pypi/v/cutde?logo=pypi"></a>
@@ -9,17 +7,35 @@
 
 # Python + CUDA TDEs from Nikkhoo and Walter 2015
 
-CUDA and OpenCL-enabled fullspace triangle dislocation elements. Benchmarked at 130 million TDEs per second. Based on the [original MATLAB code from Nikhoo and Walter 2015.](https://volcanodeformation.com/software).
+CUDA and OpenCL-enabled fullspace triangle dislocation elements. Benchmarked at 130 million TDEs per second. Based on the [original MATLAB code from Nikhoo and Walter 2015.](https://volcanodeformation.com/software)
 
 See below for usage and installation instructions.
 
-### An example
+<!--ts-->
+   * [Python + CUDA TDEs from Nikkhoo and Walter 2015](#python--cuda-tdes-from-nikkhoo-and-walter-2015)
+   * [Usage documentation](#usage-documentation)
+      * [I want stress.](#i-want-stress)
+      * [All pairs](#all-pairs)
+   * [Installation](#installation)
+      * [PyCUDA](#pycuda)
+      * [Mac OS X](#mac-os-x)
+      * [Ubuntu + PyOpenCL/PoCL](#ubuntu--pyopenclpocl)
+      * [Ubuntu + PyOpenCL with system drivers**](#ubuntu--pyopencl-with-system-drivers)
+      * [Windows](#windows)
+      * [Something else](#something-else)
+      * [Why can't I use Apple CPU OpenCL?](#why-cant-i-use-apple-cpu-opencl)
+   * [Development](#development)
 
-```
+<!-- Added by: tbent, at: Mon 05 Apr 2021 05:10:57 PM EDT -->
+
+<!--te-->
+
+```python
 
-import cutde
-import numpy as np
 import matplotlib.pyplot as plt
+import numpy as np
+
+import cutde
 
 xs = np.linspace(-2, 2, 200)
 ys = np.linspace(-2, 2, 200)
@@ -43,15 +59,15 @@ plt.contour(
     obsx, obsy, disp[:, :, 0], colors="k", linestyles="-", linewidths=0.5, levels=21
 )
 plt.colorbar(cntf)
-plt.title(f"$u_x$")
+plt.title("$u_x$")
 plt.tight_layout()
 plt.savefig("docs/example.png", bbox_inches="tight")
-}
+
 ```
 
 ![docs/example.png](docs/example.png)
 
-### Usage documentation
+# Usage documentation
 
 Usage is really simple:
 
@@ -72,7 +88,7 @@ IMPORTANT: N should be the same for all these arrays. There is exactly one trian
 * The output `disp` is a `(N, 3)` array with displacement components in the x, y, z directions.
 * The output `strain` is a `(N, 6)` array representing a symmetric tensor. `strain[:,0]` is the xx component of strain, 1 is yy, 2 is zz, 3 is xy, 4 is xz, and 5 is  yz.
 
-### I want stress.
+## I want stress.
 
 Use:
 
@@ -82,7 +98,7 @@ stress = cutde.strain_to_stress(strain, sm, nu)
 
 to convert from stress to strain assuming isotropic linear elasticity. `sm` is the shear modulus and `nu` is the Poisson ratio.
 
-### All pairs
+## All pairs
 
 If, instead, you want to create a matrix representing the interaction between every observation point and every source triangle, there is a different interface:
 
@@ -102,55 +118,58 @@ strain = cutde.strain_all_pairs(pts, tris, slips, nu)
 
 Note that to use the `strain_to_stress` function, you'll need to reshape the output strain to be `(N_OBS_PTS * N_SRC_TRIS, 6)`.
 
-### Installation
+# Installation
 
 To install `cutde` itself run:
 ```
 pip install cutde
 ```
 
-Next, make sure you are using `conda-forge` with:
-```
-conda config --prepend channels conda-forge
-```
-
 Then, install either PyCUDA or PyOpenCL following the directions below.
 
-**PyCUDA** If you have an NVIDIA GPU, install PyCUDA with:
+## PyCUDA
+If you have an NVIDIA GPU, install PyCUDA with:
 ```
+conda config --prepend channels conda-forge
 conda install -c conda-forge pycuda
 ```
 
-**PyOpenCL on Mac OS X** Install PyOpenCL and the PoCL OpenCL driver with:
+## Mac OS X
+Install PyOpenCL and the PoCL OpenCL driver with:
 ```
+conda config --prepend channels conda-forge
 conda install pocl pyopencl
 ```
 
-**PyOpenCL on Ubuntu with PoCL** Just like on a Mac:
+## Ubuntu + PyOpenCL/PoCL
+
+Just like on a Mac:
 ```
+conda config --prepend channels conda-forge
 conda install pocl pyopencl
 ```
 
-**PyOpenCL on Ubuntu with system drivers** 
+
+## Ubuntu + PyOpenCL with system drivers** 
 ```
 conda install pyopencl ocl-icd ocl-icd-system
 ```
 You will need to install the system OpenCL drivers yourself depending on the hardware you have. See the "Something else" section below.
 
-**Windows** I'm not aware of anyone testing cutde on Windows yet. It should not be difficult to install. I would expect that you install pyopencl via conda and then install the OpenCL libraries and drivers that are provided by your hardware vendor. See the "Something else" section below.
-```
-conda install pyopencl 
-```
+## Windows
+
+I'm not aware of anyone testing cutde on Windows yet. It should not be difficult to install. I would expect that you install pyopencl via conda and then install the OpenCL libraries and drivers that are provided by your hardware vendor. See the "Something else" section below.
 
-**Something else**  I'd suggest starting by trying the instructions for the system most similar to yours above. If that doesn't work, never fear! OpenCL should be installable on almost all recent hardware and typical operating systems. [These directions can be helpful.](https://documen.tician.de/pyopencl/misc.html#installing-from-conda-forge). I am happy to try to help if you have OpenCL installation issues, but I can't promise to be useful.
+## Something else
+I'd suggest starting by trying the instructions for the system most similar to yours above. If that doesn't work, never fear! OpenCL should be installable on almost all recent hardware and typical operating systems. [These directions can be helpful.](https://documen.tician.de/pyopencl/misc.html#installing-from-conda-forge). I am happy to try to help if you have OpenCL installation issues, but I can't promise to be useful.
 
-### Why can't I use Apple CPU OpenCL?
+## Why can't I use Apple CPU OpenCL?
 
 You might have gotten the message: `cutde does not support the Apple CPU OpenCL implementation and no other platform or device was found. Please consult the cutde README.`
 
 The Apple OpenCL implementation for Intel CPUs has very poor support for the OpenCL standard and causes lots of difficult-to-resolve errors. Instead, please use [the PoCL implementation](http://portablecl.org/). You can install it with `conda install -c conda-forge pocl`.
 
-### Development
+# Development
 
 For developing `cutde`, clone the repo and set up your conda environment based on the `environment.yml` with:
 

diff --git a/docs/README-tmpl.md b/docs/README-tmpl.md
@@ -1,31 +1,31 @@
-# cutde
-
 <p align=center>
     <a target="_blank" href="https://www.python.org/downloads/" title="Python version"><img src="https://img.shields.io/badge/python-%3E=_3.6-green.svg"></a>
     <a target="_blank" href="https://pypi.org/project/cutde/" title="PyPI version"><img src="https://img.shields.io/pypi/v/cutde?logo=pypi"></a>
     <!-- <a target="_blank" href="https://pypi.org/project/cutde/" title="PyPI"><img src="https://img.shields.io/pypi/dm/cutde"></a> -->
     <a target="_blank" href="LICENSE" title="License: MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+    <a target="_blank" href="https://github.com/tbenthompson/cutde/actions" title="Test Status"><img src="https://github.com/tbenthompson/cutde/actions/workflows/test.yml/badge.svg"></a>
 </a>
 
 # Python + CUDA TDEs from Nikkhoo and Walter 2015
 
-CUDA and OpenCL-enabled fullspace triangle dislocation elements. Benchmarked at 130 million TDEs per second. Based on the [original MATLAB code from Nikhoo and Walter 2015.](https://volcanodeformation.com/software).
+CUDA and OpenCL-enabled fullspace triangle dislocation elements. Benchmarked at 130 million TDEs per second. Based on the [original MATLAB code from Nikhoo and Walter 2015.](https://volcanodeformation.com/software)
 
 See below for usage and installation instructions.
 
-### An example
+<!--ts-->
+<!--te-->
 
-```
+```python
 <%
 with open('docs/example.py', 'r') as f:
     example_contents = f.read()
 %>
-${example_contents}}
+${example_contents}
 ```
 
 ![docs/example.png](docs/example.png)
 
-### Usage documentation
+# Usage documentation
 
 Usage is really simple:
 
@@ -46,7 +46,7 @@ IMPORTANT: N should be the same for all these arrays. There is exactly one trian
 * The output `disp` is a `(N, 3)` array with displacement components in the x, y, z directions.
 * The output `strain` is a `(N, 6)` array representing a symmetric tensor. `strain[:,0]` is the xx component of strain, 1 is yy, 2 is zz, 3 is xy, 4 is xz, and 5 is  yz.
 
-### I want stress.
+## I want stress.
 
 Use:
 
@@ -56,7 +56,7 @@ stress = cutde.strain_to_stress(strain, sm, nu)
 
 to convert from stress to strain assuming isotropic linear elasticity. `sm` is the shear modulus and `nu` is the Poisson ratio.
 
-### All pairs
+## All pairs
 
 If, instead, you want to create a matrix representing the interaction between every observation point and every source triangle, there is a different interface:
 
@@ -76,55 +76,58 @@ strain = cutde.strain_all_pairs(pts, tris, slips, nu)
 
 Note that to use the `strain_to_stress` function, you'll need to reshape the output strain to be `(N_OBS_PTS * N_SRC_TRIS, 6)`.
 
-### Installation
+# Installation
 
 To install `cutde` itself run:
 ```
 pip install cutde
 ```
 
-Next, make sure you are using `conda-forge` with:
-```
-conda config --prepend channels conda-forge
-```
-
 Then, install either PyCUDA or PyOpenCL following the directions below.
 
-**PyCUDA** If you have an NVIDIA GPU, install PyCUDA with:
+## PyCUDA
+If you have an NVIDIA GPU, install PyCUDA with:
 ```
+conda config --prepend channels conda-forge
 conda install -c conda-forge pycuda
 ```
 
-**PyOpenCL on Mac OS X** Install PyOpenCL and the PoCL OpenCL driver with:
+## Mac OS X
+Install PyOpenCL and the PoCL OpenCL driver with:
 ```
+conda config --prepend channels conda-forge
 conda install pocl pyopencl
 ```
 
-**PyOpenCL on Ubuntu with PoCL** Just like on a Mac:
+## Ubuntu + PyOpenCL/PoCL
+
+Just like on a Mac:
 ```
+conda config --prepend channels conda-forge
 conda install pocl pyopencl
 ```
 
-**PyOpenCL on Ubuntu with system drivers** 
+
+## Ubuntu + PyOpenCL with system drivers** 
 ```
 conda install pyopencl ocl-icd ocl-icd-system
 ```
 You will need to install the system OpenCL drivers yourself depending on the hardware you have. See the "Something else" section below.
 
-**Windows** I'm not aware of anyone testing cutde on Windows yet. It should not be difficult to install. I would expect that you install pyopencl via conda and then install the OpenCL libraries and drivers that are provided by your hardware vendor. See the "Something else" section below.
-```
-conda install pyopencl 
-```
+## Windows
+
+I'm not aware of anyone testing cutde on Windows yet. It should not be difficult to install. I would expect that you install pyopencl via conda and then install the OpenCL libraries and drivers that are provided by your hardware vendor. See the "Something else" section below.
 
-**Something else**  I'd suggest starting by trying the instructions for the system most similar to yours above. If that doesn't work, never fear! OpenCL should be installable on almost all recent hardware and typical operating systems. [These directions can be helpful.](https://documen.tician.de/pyopencl/misc.html#installing-from-conda-forge). I am happy to try to help if you have OpenCL installation issues, but I can't promise to be useful.
+## Something else
+I'd suggest starting by trying the instructions for the system most similar to yours above. If that doesn't work, never fear! OpenCL should be installable on almost all recent hardware and typical operating systems. [These directions can be helpful.](https://documen.tician.de/pyopencl/misc.html#installing-from-conda-forge). I am happy to try to help if you have OpenCL installation issues, but I can't promise to be useful.
 
-### Why can't I use Apple CPU OpenCL?
+## Why can't I use Apple CPU OpenCL?
 
 You might have gotten the message: `cutde does not support the Apple CPU OpenCL implementation and no other platform or device was found. Please consult the cutde README.`
 
 The Apple OpenCL implementation for Intel CPUs has very poor support for the OpenCL standard and causes lots of difficult-to-resolve errors. Instead, please use [the PoCL implementation](http://portablecl.org/). You can install it with `conda install -c conda-forge pocl`.
 
-### Development
+# Development
 
 For developing `cutde`, clone the repo and set up your conda environment based on the `environment.yml` with:
 

diff --git a/docs/build → docs/build_docs b/docs/build → docs/build_docs
@@ -1,3 +1,4 @@
 #!/bin/bash
 python docs/example.py
 python docs/tmpl_readme.py
+gh-md-toc --insert --no-backup README.md