From cc85ab7d9821ec651bd588f80f7128a307dad3b6 Mon Sep 17 00:00:00 2001
From: ckhurana <ckhurana@lap-khurana.psfc.mit.edu>
Date: Mon, 20 Oct 2025 11:15:43 -0400
Subject: [PATCH] added settings chapter

---
 book/_toc.yml                     |   4 ++
 book/content/settings/settings.md | 101 ++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 book/content/settings/settings.md

diff --git a/book/_toc.yml b/book/_toc.yml
index 6cac4fa..1c10d91 100644
--- a/book/_toc.yml
+++ b/book/_toc.yml
@@ -27,6 +27,10 @@ parts:
     - file: content/species_reactions/reactions
     - file: content/species_reactions/surface_reactions
 
+  - caption: Settings
+    chapters:
+    - file: content/settings/settings
+
   - caption: Applications
     chapters:
     - file: content/applications/task02
diff --git a/book/content/settings/settings.md b/book/content/settings/settings.md
new file mode 100644
index 0000000..44fa6e5
--- /dev/null
+++ b/book/content/settings/settings.md
@@ -0,0 +1,101 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.17.3
+kernelspec:
+  display_name: festim-workshop
+  language: python
+  name: python3
+---
+
+# Settings #
+
++++
+
+The settings of a FESTIM simulation are defined with a `festim.Settings` object. This tutorial provides information for defining required and optional settings for users to customize their simulations.
+
+Objectives:
+* Defining tolerances and solver settings
+* Setting up transient or steady-state simulations
+
++++
+
+## Defining tolerances and solver settings ##
+
+The required settings for any FESTIM simulation are the absolute and relative tolerances, while users can optionally specify the maximum number of iterations for the solver, degree order for finite element, and whether to use residual or incremental convergence criterion (for Newton solvers).
+
+We can define the tolerances using `atol` (absolute) and `rtol` (relative):
+
+```{code-cell} ipython3
+import festim as F
+
+settings = F.Settings(
+    atol=1e10,
+    rtol=1e-10
+)
+```
+
+To specify the maximum number of iterations (which defaults to 30), we can use `max_iterations`:
+
+```{code-cell} ipython3
+settings = F.Settings(
+    atol=1e10,
+    rtol=1e-10,
+    max_iterations=50
+)
+```
+
+To specify the degree order of the finite element (which defaults to 1), we can use `element_degree`:
+
+```{code-cell} ipython3
+settings = F.Settings(
+    atol=1e10,
+    rtol=1e-10,
+    element_degree=2
+    )
+```
+
+To specify the convergence criterion, we can use `convergence_criterion` and strings for `residual` and `incremental`. For a residual-based convergence:
+
+```{code-cell} ipython3
+settings = F.Settings(
+    atol=1e10,
+    rtol=1e-10,
+    convergence_criterion='residual'
+)
+```
+
+## Setting up transient or steady-state simulations ##
+
+For transient simulations, we need to define `final_time` and `stepsize`, while for steady-state problems, we simply need to set `transient` to `False`.
+
+For example, if we have an absolute and relative tolerance of `1e10` and `1e-10`, respectively, we can define the steady-state settings as:
+
+```{code-cell} ipython3
+import festim as F
+
+my_settings = F.Settings(
+    atol=1e10,
+    rtol=1e-10,
+    transient=False,
+)
+```
+
+For a transient simulation with a run-time of 10 seconds and stepsize of 2 seconds:
+
+```{code-cell} ipython3
+my_settings = F.Settings(
+    atol=1e10,
+    rtol=1e-10,
+    final_time=10,
+    stepsize=2
+)
+```
+
+```{note}
+FESTIM defaults the `transient` setting to `True`, while the stepsize and final time defaults to `None`.
+```