Add pull request template

.github/pull_request_template.md

@@ -0,0 +1,48 @@
+<!-- 
+Thanks for contributing a pull request to SimPEG user tutorials!
+Remember to use a personal fork of SimPEG user tutorials to propose changes.
+
+Check out the stages of a pull request at
+https://docs.simpeg.xyz/content/getting_started/contributing/pull-requests.html
+
+Note that we are a team of volunteers and we appreciate your
+patience during the review process.
+
+Again, thanks for contributing!
+
+Feel free to remove lines from this template that do not apply to you pull request.
+-->
+
+#### Summary
+<!-- Add a summary of this Pull Request. Explain what it provides as tutorial material. -->
+
+#### PR Checklist
+* [ ] If this is a work in progress PR, set as a Draft PR
+* [ ] General
+    * [ ] Notebook is compatible with latest SimPEG release
+    * [ ] No deprecated functions and/or input arguments are being used
+    * [ ] Coding cells linted according to the [style guides](https://docs.simpeg.xyz/latest/content/getting_started/contributing/code-style.html).
+* [ ] Introduction is complete:
+    * [ ] Title and author added to notebook
+    * [ ] Admonitions for notebook difficulty and computational resources have been added
+    * [ ] Keywords list has been added
+    * [ ] Summary paragraph describing the tutorial has been added
+    * [ ] Learning objectives have been listed
+    * [ ] Hyperlinks to other tutorial notebooks added if necessary
+* [ ] For sections and subsections:
+    * [ ] A header and short summary of what is being done
+    * [ ] Links to API documentation added for all classes and functions that are used
+    * [ ] Newly introduced functionality is explained, or links are provided to relevant materials
+    * [ ] The approach taken when choosing hyperparameter values is explained. The use of ad hoc values without explanation is discouraged
+    * [ ] All figures are legible and rendered appropriately
+* [ ] Marked as ready for review (if this is was a draft PR), and converted to a pull request
+* [ ] Tagged ``@simpeg/simpeg-developers`` when ready for review
+
+
+#### Additional information
+<!--Any additional information you think is important.-->
+
+
+<!--
+Once all tests pass and the code has been reviewed and approved, it will be merged into main
+-->

index.md

@@ -106,3 +106,10 @@ Requires moderate computational resources. Run-times may exceed several minutes
 The computational resources required to execute this notebook exceed those provided by standard laptop computers. To execute the notebook, please deploy to a cluster computing environment.
 ```
 
+Want to Add a Tutorial?
+-----------------------
+
+Please visit the [Contributing to User Tutorials](notebooks/contributing_index.md) page to find out how you can add a tutorial.
+
+
+

myst.yml

@@ -116,6 +116,11 @@ project:
       children:
         - file: notebooks/12-pgi-inversion/plot_inv_1_joint_pf_pgi_full_info_tutorial.ipynb
         - file: notebooks/12-pgi-inversion/plot_inv_2_joint_pf_pgi_no_info_tutorial.ipynb
+    - file: notebooks/contributing_index.md
+      children:
+        - file: notebooks/contributing/build_website.md
+        - file: notebooks/contributing/formatting.md
+        - file: notebooks/contributing/pull_request.md
 
 site:
   template: book-theme

notebooks/03-gravity/fwd_gravity_anomaly_3d.ipynb

@@ -89,11 +89,11 @@
     "import numpy as np\n",
     "from scipy.interpolate import LinearNDInterpolator\n",
     "import matplotlib as mpl\n",
-    "\n",
-    "mpl.rcParams.update({\"font.size\": 14})\n",
     "import matplotlib.pyplot as plt\n",
     "import os\n",
     "\n",
+    "mpl.rcParams.update({\"font.size\": 14})\n",
+    "\n",
     "save_output = False  # Optional"
    ]
   },

notebooks/03-gravity/fwd_gravity_gradiometry_3d.ipynb

@@ -92,9 +92,9 @@
     "import numpy as np\n",
     "from scipy.interpolate import LinearNDInterpolator\n",
     "import matplotlib as mpl\n",
+    "import matplotlib.pyplot as plt\n",
     "\n",
     "mpl.rcParams.update({\"font.size\": 14})\n",
-    "import matplotlib.pyplot as plt\n",
     "\n",
     "save_output = False  # Optional"
    ]

notebooks/04-magnetics/fwd_magnetics_induced_3d.ipynb

@@ -90,11 +90,11 @@
     "import numpy as np\n",
     "from scipy.interpolate import LinearNDInterpolator\n",
     "import matplotlib as mpl\n",
-    "\n",
-    "mpl.rcParams.update({\"font.size\": 14})\n",
     "import matplotlib.pyplot as plt\n",
     "import os\n",
     "\n",
+    "mpl.rcParams.update({\"font.size\": 14})\n",
+    "\n",
     "save_output = False  # Optional"
    ]
   },

notebooks/04-magnetics/fwd_magnetics_mvi_3d.ipynb

@@ -92,9 +92,9 @@
     "from scipy.interpolate import LinearNDInterpolator\n",
     "from scipy.constants import mu_0\n",
     "import matplotlib as mpl\n",
+    "import matplotlib.pyplot as plt\n",
     "\n",
     "mpl.rcParams.update({\"font.size\": 14})\n",
-    "import matplotlib.pyplot as plt\n",
     "\n",
     "save_output = False  # Optional"
    ]

notebooks/07-fdem/fwd_fdem_3d.ipynb

@@ -82,7 +82,6 @@
     "from discretize.utils import mkvc, active_from_xyz\n",
     "\n",
     "# Common Python functionality\n",
-    "import os\n",
     "import numpy as np\n",
     "import matplotlib as mpl\n",
     "import matplotlib.pyplot as plt\n",
@@ -843,56 +842,6 @@
     "\n",
     "plt.show()"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Optional: Export Data\n",
-    "\n",
-    "Write the true model, data and topography\n",
-    "\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 21,
-   "metadata": {
-    "execution": {
-     "iopub.execute_input": "2025-05-23T17:19:25.643898Z",
-     "iopub.status.busy": "2025-05-23T17:19:25.643584Z",
-     "iopub.status.idle": "2025-05-23T17:19:25.648762Z",
-     "shell.execute_reply": "2025-05-23T17:19:25.648248Z"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "if save_file:\n",
-    "    dir_path = os.path.dirname(fdem.__file__).split(os.path.sep)[:-3]\n",
-    "    dir_path.extend([\"tutorials\", \"assets\", \"fdem\"])\n",
-    "    dir_path = os.path.sep.join(dir_path) + os.path.sep\n",
-    "\n",
-    "    # Write topography\n",
-    "    fname = dir_path + \"fdem_topo.txt\"\n",
-    "    np.savetxt(fname, np.c_[topo_xyz], fmt=\"%.4e\")\n",
-    "\n",
-    "    # Write data with 2% noise added\n",
-    "    fname = dir_path + \"fdem_data.obs\"\n",
-    "    bz_real = bz_real + 1e-14 * np.random.rand(len(bz_real))\n",
-    "    bz_imag = bz_imag + 1e-14 * np.random.rand(len(bz_imag))\n",
-    "    f_vec = np.kron(frequencies, np.ones(ntx))\n",
-    "    receiver_locations = np.kron(np.ones((len(frequencies), 1)), receiver_locations)\n",
-    "\n",
-    "    np.savetxt(fname, np.c_[f_vec, receiver_locations, bz_real, bz_imag], fmt=\"%.4e\")\n",
-    "\n",
-    "    # Plot true model\n",
-    "    output_model = plotting_map * model\n",
-    "    output_model[np.isnan(output_model)] = 1e-8\n",
-    "\n",
-    "    fname = dir_path + \"true_model.txt\"\n",
-    "    np.savetxt(fname, output_model, fmt=\"%.4e\")"
-   ]
   }
  ],
  "metadata": {

notebooks/08-tdem/fwd_tdem_3d.ipynb

@@ -82,7 +82,6 @@
     "from discretize.utils import mkvc, active_from_xyz\n",
     "\n",
     "# Common Python functionality\n",
-    "import os\n",
     "import numpy as np\n",
     "import matplotlib as mpl\n",
     "import matplotlib.pyplot as plt\n",
@@ -913,56 +912,6 @@
     "\n",
     "plt.show()"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Optional: Export Data\n",
-    "\n",
-    "Write the true model, data and topography\n",
-    "\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 23,
-   "metadata": {
-    "execution": {
-     "iopub.execute_input": "2025-05-23T17:54:48.125857Z",
-     "iopub.status.busy": "2025-05-23T17:54:48.125627Z",
-     "iopub.status.idle": "2025-05-23T17:54:48.132415Z",
-     "shell.execute_reply": "2025-05-23T17:54:48.131374Z"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "if save_file:\n",
-    "    dir_path = os.path.dirname(tdem.__file__).split(os.path.sep)[:-3]\n",
-    "    dir_path.extend([\"tutorials\", \"assets\", \"tdem\"])\n",
-    "    dir_path = os.path.sep.join(dir_path) + os.path.sep\n",
-    "\n",
-    "    fname = dir_path + \"tdem_topo.txt\"\n",
-    "    np.savetxt(fname, np.c_[topo_xyz], fmt=\"%.4e\")\n",
-    "\n",
-    "    # Write data with 2% noise added\n",
-    "    fname = dir_path + \"tdem_data.obs\"\n",
-    "    rng = np.random.default_rng(seed=42)\n",
-    "    noise = rng.uniform(low=0.0, high=0.02 * np.abs(dpred), size=len(dpred))\n",
-    "    dpred += noise\n",
-    "    t_vec = np.kron(np.ones(ntx), time_channels)\n",
-    "    receiver_locations = np.kron(receiver_locations, np.ones((len(time_channels), 1)))\n",
-    "\n",
-    "    np.savetxt(fname, np.c_[receiver_locations, t_vec, dpred], fmt=\"%.4e\")\n",
-    "\n",
-    "    # Plot true model\n",
-    "    output_model = plotting_map * model\n",
-    "    output_model[np.isnan(output_model)] = 1e-8\n",
-    "\n",
-    "    fname = dir_path + \"true_model.txt\"\n",
-    "    np.savetxt(fname, output_model, fmt=\"%.4e\")"
-   ]
   }
  ],
  "metadata": {

notebooks/contributing/build_website.md

@@ -0,0 +1,109 @@
+Building the User Tutorials Website Locally
+===========================================
+
+Here, we provide instructions for setting up an appropriate Python environment and building the SimPEG user tutorials website locally with [MyST](https://mystmd.org/).
+
+## Step 1: Cloning the GitHub Repository
+
+The URL for the SimPEG user tutorials GitHub repository is: https://github.com/simpeg/user-tutorials/. If using the Git Bash shell:
+
+```bash
+git clone https://github.com/simpeg/user-tutorials
+cd user-tutorials
+```
+
+## Step 2: Setting Up a Python Environment
+
+The Jupyter notebooks containing the tutorials are maintained to run properly using the [latest release of SimPEG](https://github.com/simpeg/simpeg/releases).
+Notebooks may not run correctly if SimPEG is being imported from an earlier release or development branch.
+The [mystmd][install-mystmd] and [nodejs](https://nodejs.org/api/packages.html) are also required to build the website locally.
+
+We advise building a Python environment from the `environment.yml` file in the root directory of the repository.
+To create the `simpeg-user-tutorials` environment using conda:
+
+```bash
+conda env create -f environment.yml
+```
+
+Once built, you can activate using:
+
+```bash
+conda activate simpeg-user-tutorials
+```
+
+## Step 3: Build and Execution Commands
+
+The SimPEG user tutorials are a collection of [Jupyter Notebook](https://jupyter.org/) (and [Markdown](https://www.markdownguide.org/getting-started/)) files,
+which [MyST][mystmd.org] builds into a website. Here, we describe the commands that contributors should be familiar with.
+
+:::{important}
+The tutorial notebooks, including their states, are tracked by GitHub. When the SimPEG user tutorials repository was cloned, all notebooks had been run and saved. Therefore, you do not need to rerun all of the notebooks prior to building the website!
+:::
+
+### Locally Build and Serve Website
+
+The following command will build the website and serve it locally.
+This will allow you to preview the website and observe any changes to notebooks on the fly.
+To locally build and serve the website:
+the website:
+
+```bash
+myst start
+```
+
+Next, follow the instructions prompted by the command to launch the local build in your brower.
+
+### Build Only
+
+The following command will build the website and store the HTML files in
+a new `_build` folder:
+
+```bash
+myst build --html
+```
+
+### Clean Cached Builds
+
+```bash
+myst clean --all
+```
+
+### Rerunning Notebooks
+
+When making alterations and rerunning notebooks, we typically do so by launching Jupyter Notebooks:
+
+```bash
+jupyter notebook
+```
+
+However, we can rerun a notebook and overwrite its output cells in place using `nbconvert`.
+To rerun a single notebook, use:
+
+```bash
+jupyter nbconvert --to notebook --execute --inplace notebook.ipynb
+```
+
+We may also want to rerun all notebooks in the repository.
+To rerun all notebooks, use:
+
+```bash
+jupyter nbconvert --to notebook --execute --inplace notebooks/**/*.ipynb
+```
+
+:::{danger}
+Rerunning all notebooks is a computationally intensive task. Some notebooks
+require significant amount of memory to allocate large sensitivity matrices.
+:::
+
+> [!IMPORTANT]
+> If you are using bash as your shell, make sure to run `shopt -s
+> globstar` to enable the `globstar` feature that allows the use of `**` for
+> filename expansion.
+
+
+
+
+[install-mystmd]: https://mystmd.org/guide/quickstart
+[jupyter]: https://jupyter.org
+[mystmd.org]: https://mystmd.org
+