Style Guide

This guide provides conventions for writing and formatting content for the Computational Geodynamics Primer.

File Organization

  • Place chapter files in the appropriate subdirectory (e.g., Part1-Fundamentals/, DraftMaterial/)
  • Use descriptive, lowercase filenames with hyphens: thermal-convection.qmd
  • Store images in Images/Diagrams/ or Images/Photos/

Mathematical Notation

Global Macros

We have defined global macros in _math-preamble.qmd. Include this at the top of each chapter:

::: {.hidden}
$$
% Global LaTeX macros for MathJax
\newcommand{\dGamma}{\mathbf{d}\boldsymbol{\Gamma}}
\newcommand{\uv}{\mathbf{u}}
\newcommand{\vv}{\mathbf{v}}
\newcommand{\nhat}{\mathbf{\hat{n}}}
\newcommand{\DIV}{\nabla\cdot}
\newcommand{\GRAD}{\nabla}
\newcommand{\CURL}{\nabla\times}
\DeclareMathOperator{\erfc}{erfc}

% Differential operators
\newcommand{\DDt}[1]{\frac{D #1}{D t}}
\newcommand{\ddt}[1]{\frac{d #1}{d t}}
\newcommand{\ppt}[1]{\frac{\partial #1}{\partial t}}
\newcommand{\ppx}[1]{\frac{\partial #1}{\partial x}}

% Color commands (MathJax compatible)
\newcommand{\Red}[1]{{\color{red} #1}}
\newcommand{\Green}[1]{{\color{green} #1}}
\newcommand{\Blue}[1]{{\color{blue} #1}}
\newcommand{\Emerald}[1]{{\color{teal} #1}}
$$
:::

Available macros include: - \uv - velocity vector \(\mathbf{u}\) - \vv - velocity vector \(\mathbf{v}\) - \DIV - divergence operator \(\nabla\cdot\) - \GRAD - gradient operator \(\nabla\) - \CURL - curl operator \(\nabla\times\) - \Red{text} - red text for emphasis - \Blue{text} - blue text - \Green{text} - green text

Equations

Use display equations with labels for important results:

$$
\DIV \sigma + \rho \mathbf{g} = 0
$$ {#eq-stokes-momentum}

Reference equations using @eq-label:

The momentum equation @eq-stokes-momentum shows...

Multi-line Equations

For multi-line equations, use the aligned or split environments:

$$
\begin{aligned}
\frac{\partial T}{\partial t} + \uv \cdot \GRAD T &= \kappa \nabla^2 T + H \\
\DIV \uv &= 0
\end{aligned}
$$

Figures

Use Markdown image syntax with labels:

![Caption describing the figure](../Images/Diagrams/filename.png){#fig-label width=450px}

Reference figures using @fig-label:

As shown in @fig-convection-cells, the...

Citations

Add references to references.bib in BibTeX format. Cite using:

The seminal work by @turcotte2014 showed...

Multiple studies [@moresi1995; @tackley2008] have demonstrated...

Code Blocks

Python Code

For executable Python code using pyodide:

```{pyodide-python}
import numpy as np
import matplotlib.pyplot as plt

# Your code here
```

For non-executable code examples:

```python
# Example code
def solve_stokes(mesh, viscosity):
    # Implementation
    pass
```

Headings

Use hierarchical headings:

# Chapter Title (automatically numbered)

## Major Section

### Subsection

#### Minor subsection (use sparingly)

Emphasis and Formatting

  • Bold for key terms on first use: **Rayleigh number**
  • Italics for emphasis: *important*
  • Code font for variables and functions: `temperature`
  • Math mode for mathematical symbols: $\eta$

Cross-References

Equations in Other Files

When referencing equations from other chapters, use @eq-label. Note that cross-file references may generate warnings during single-file rendering.

Callout Blocks

Use callout blocks to highlight important information:

:::{.callout-note}
This is a note.
:::

:::{.callout-tip}
This is a helpful tip.
:::

:::{.callout-warning}
This is a warning about potential issues.
:::

:::{.callout-important}
This is important information.
:::

:::{.callout-caution}
Exercise caution in this situation.
:::

Add collapse="true" to make them collapsible:

:::{.callout-note collapse="true"}
## Click to expand
Hidden content here...
:::

Physical Quantities and Units

  • Use SI units by default
  • Clearly state non-dimensional forms
  • Use consistent notation for physical quantities throughout the book

Common Notation

  • \(\eta\) - dynamic viscosity
  • \(\rho\) - density
  • \(T\) - temperature
  • \(\mathbf{u}\), \(\mathbf{v}\) - velocity vectors
  • \(p\) - pressure
  • \(\kappa\) - thermal diffusivity
  • \(\alpha\) - thermal expansivity
  • \(g\) - gravitational acceleration

Examples

See the Example: Using Citations and Math chapter for a working demonstration of these conventions.