Skip to content

Commit 3a96e9e

Browse files
ggormanggorman
committed
Add Quarto book structure converted from DocOnce
- Convert all chapters from DocOnce (.do.txt) to Quarto (.qmd) format - Add _quarto.yml configuration for PDF and HTML output - Add index.qmd as book entry point - Add references.bib bibliography - Add conversion scripts in scripts/ - Add issues.md documenting remaining cross-reference warnings - Rename conflicting LaTeX macros (\u -> \uu, \v -> \vv) - Wrap alignat environments in raw LaTeX blocks - Exclude large image files (>500KB) from this commit
1 parent 6cef326 commit 3a96e9e

362 files changed

Lines changed: 41813 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ build/
1818
*~
1919
.*~
2020
*.old
21+
*.old~~
2122
tmp*
2223
temp*
2324
.#*
@@ -66,3 +67,6 @@ tmp_mako__*.do.txt
6667
tmp_preprocess__*.do.txt
6768
# Test files:
6869
title_test.*
70+
71+
/.quarto/
72+
**/*.quarto_ipynb

‎.typos.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[default.extend-words]
2+
# Vietnamese name (Thanh-Ha Le Thi)
3+
Thi = "Thi"
4+
# Equation label suffix (exact solution "u_e")
5+
ue = "ue"

‎CLAUDE.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the source repository for *Finite Difference Computing with PDEs - A Modern Software Approach* by Hans Petter Langtangen and Svein Linge. The book teaches finite difference methods for solving PDEs through Python implementations.
8+
9+
## Build Commands
10+
11+
### Build Book PDF
12+
13+
```bash
14+
cd doc/.src/book
15+
bash make.sh nospell # Skip spellcheck (faster)
16+
bash make.sh # With spellcheck
17+
```
18+
19+
### Build Individual Chapter
20+
21+
```bash
22+
cd doc/.src/chapters/vib # or wave, diffu, advec, nonlin, trunc, softeng2, formulas
23+
bash make.sh
24+
```
25+
26+
### Run Tests
27+
28+
```bash
29+
pytest src/ # Run all tests
30+
pytest src/vib/vib.py -v # Run tests in specific file
31+
python -m pytest --tb=short # With short traceback
32+
```
33+
34+
### Linting
35+
36+
```bash
37+
ruff check src/ # Check for linting errors
38+
isort --check-only src/ # Check import ordering
39+
isort src/ # Fix import ordering
40+
pre-commit run --all-files # Run all pre-commit hooks
41+
pre-commit run --hook-stage manual # Run auto-fix hooks
42+
```
43+
44+
## Architecture
45+
46+
### Directory Structure
47+
48+
- `src/` - Python source code organized by chapter (vib, wave, diffu, nonlin, etc.)
49+
- `doc/.src/book/` - Main book build (book.do.txt includes all chapters)
50+
- `doc/.src/chapters/` - DocOnce source for each chapter:
51+
- `*.do.txt` - DocOnce markup files (main content)
52+
- `fig-*/` - Figures for the chapter
53+
- `exer-*/` - Exercise solutions and supporting code
54+
- `.dict4spell.txt` - Chapter-specific spelling dictionary
55+
56+
### DocOnce Document Format
57+
58+
The book uses [DocOnce](https://github.com/doconce/doconce), a markup language that compiles to LaTeX/PDF. Key syntax:
59+
60+
- `@@@CODE path/to/file.py fromto: start_pattern@end_pattern` - Include code snippet between patterns
61+
- `!bc pycod` / `!ec` - Python code block
62+
- `!bt` / `!et` - LaTeX math block
63+
- `idx{term}` - Index entry
64+
- `ref{label}` - Cross-reference
65+
- `# #include "file.do.txt"` - Include another file
66+
67+
### Code Organization Pattern
68+
69+
Each chapter's Python code lives in `src/CHAPTER/` and is referenced by documentation in `doc/.src/chapters/CHAPTER/`. The `@@@CODE` directive pulls code snippets directly from source files into the documentation, keeping code and docs in sync.
70+
71+
## Pre-commit Hooks
72+
73+
Pre-commit hooks run automatically on commit:
74+
75+
- trailing-whitespace, end-of-file-fixer
76+
- isort (import ordering check)
77+
- ruff (linting check)
78+
- typos (spell check)
79+
- markdownlint-cli2 (markdown check)
80+
81+
## Key Dependencies
82+
83+
- **doconce** - Document generation from .do.txt files
84+
- **numpy, scipy, matplotlib, sympy** - Scientific Python stack for examples
85+
- **pdflatex** - LaTeX compilation (requires TeX Live installation)
86+
87+
## Build Output
88+
89+
- `doc/.src/book/book.pdf` - Generated book PDF
90+
- `doc/pub/book/pdf/fdm-book.pdf` - Published copy of book PDF

‎_quarto.yml‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
project:
2+
type: book
3+
output-dir: _book
4+
5+
book:
6+
title: "Finite Difference Computing with PDEs"
7+
subtitle: "A Modern Software Approach"
8+
author:
9+
- name: Hans Petter Langtangen
10+
- name: Svein Linge
11+
date: today
12+
chapters:
13+
- index.qmd
14+
- chapters/preface/index.qmd
15+
- part: "Main Chapters"
16+
chapters:
17+
- chapters/vib/index.qmd
18+
- chapters/wave/index.qmd
19+
- chapters/diffu/index.qmd
20+
- chapters/advec/index.qmd
21+
- chapters/nonlin/index.qmd
22+
- part: "Appendices"
23+
chapters:
24+
- chapters/appendices/formulas/index.qmd
25+
- chapters/appendices/trunc/index.qmd
26+
- chapters/appendices/softeng2/index.qmd
27+
repo-url: https://github.com/devitocodes/devito_book
28+
site-url: https://devitocodes.github.io/devito_book
29+
30+
bibliography: references.bib
31+
32+
format:
33+
html:
34+
theme: cosmo
35+
code-fold: false
36+
toc: true
37+
number-sections: true
38+
crossref:
39+
chapters: true
40+
pdf:
41+
documentclass: book
42+
papersize: letter
43+
toc: true
44+
number-sections: true
45+
colorlinks: true
46+
default-image-extension: png
47+
pdf-engine: pdflatex
48+
include-in-header:
49+
text: |
50+
% Required packages
51+
\usepackage{bm} % For bold math symbols
52+
53+
% Custom LaTeX macros from the book
54+
\newcommand{\half}{\frac{1}{2}}
55+
\newcommand{\halfi}{{1/2}}
56+
\newcommand{\tp}{\thinspace .}
57+
58+
\newcommand{\uex}{u_{\mbox{\footnotesize e}}}
59+
\newcommand{\uexd}[1]{u_{\mbox{\footnotesize e}, #1}}
60+
\newcommand{\vex}{v_{\mbox{\footnotesize e}}}
61+
\newcommand{\Vex}{V_{\mbox{\footnotesize e}}}
62+
\newcommand{\vexd}[1]{v_{\mbox{\footnotesize e}, #1}}
63+
\newcommand{\Aex}{A_{\mbox{\footnotesize e}}}
64+
\newcommand{\wex}{w_{\mbox{\footnotesize e}}}
65+
66+
% Operators
67+
\newcommand{\Ddt}[1]{\frac{D #1}{dt}}
68+
\newcommand{\E}[1]{\hbox{E}\lbrack #1 \rbrack}
69+
\newcommand{\Var}[1]{\hbox{Var}\lbrack #1 \rbrack}
70+
\newcommand{\Std}[1]{\hbox{Std}\lbrack #1 \rbrack}
71+
72+
\newcommand{\xpoint}{\bm{x}}
73+
\newcommand{\normalvec}{\bm{n}}
74+
\newcommand{\Oof}[1]{\mathcal{O}(#1)}
75+
76+
% Boldface vectors/tensors
77+
\newcommand{\x}{\bm{x}}
78+
\newcommand{\X}{\bm{X}}
79+
\newcommand{\uu}{\bm{u}}
80+
\newcommand{\vv}{\bm{v}}
81+
\newcommand{\w}{\bm{w}}
82+
\newcommand{\acc}{\bm{a}}
83+
\newcommand{\rpos}{\bm{r}}
84+
\newcommand{\V}{\bm{V}}
85+
\newcommand{\e}{\bm{e}}
86+
\newcommand{\f}{\bm{f}}
87+
\newcommand{\F}{\bm{F}}
88+
\newcommand{\stress}{\bm{\sigma}}
89+
\newcommand{\strain}{\bm{\varepsilon}}
90+
\newcommand{\stressc}{{\sigma}}
91+
\newcommand{\strainc}{{\varepsilon}}
92+
\newcommand{\I}{\bm{I}}
93+
\newcommand{\T}{\bm{T}}
94+
\newcommand{\U}{\bm{U}}
95+
\newcommand{\q}{\bm{q}}
96+
\newcommand{\g}{\bm{g}}
97+
98+
\newcommand{\dfc}{\alpha}
99+
% Unit vectors
100+
\newcommand{\ii}{\bm{i}}
101+
\newcommand{\jj}{\bm{j}}
102+
\newcommand{\kk}{\bm{k}}
103+
\newcommand{\ir}{\bm{i}_r}
104+
\newcommand{\ith}{\bm{i}_{\theta}}
105+
\newcommand{\iz}{\bm{i}_z}
106+
107+
% Index sets
108+
\newcommand{\Ix}{\mathcal{I}_x}
109+
\newcommand{\Iy}{\mathcal{I}_y}
110+
\newcommand{\Iz}{\mathcal{I}_z}
111+
\newcommand{\It}{\mathcal{I}_t}
112+
\newcommand{\If}{\mathcal{I}_s}
113+
\newcommand{\Ifd}{{I_d}}
114+
\newcommand{\Ifb}{{I_b}}
115+
\newcommand{\setb}[1]{#1^0}
116+
\newcommand{\sete}[1]{#1^{-1}}
117+
\newcommand{\setl}[1]{#1^-}
118+
\newcommand{\setr}[1]{#1^+}
119+
\newcommand{\seti}[1]{#1^i}
120+
\newcommand{\sequencei}[1]{\left\{ {#1}_i \right\}_{i\in\If}}
121+
\newcommand{\sequencej}[1]{\left\{ {#1}_j \right\}_{j\in\If}}
122+
123+
% Superscripts for intermediate solutions
124+
\newcommand{\stepzero}{*}
125+
\newcommand{\stephalf}{***}
126+
\newcommand{\stepone}{**}
127+
128+
% Finite elements
129+
\newcommand{\basphi}{\varphi}
130+
\newcommand{\baspsi}{\psi}
131+
\newcommand{\refphi}{\tilde\basphi}
132+
\newcommand{\psib}{\bm{\psi}}
133+
\newcommand{\sinL}[1]{\sin\left((#1+1)\pi\frac{x}{L}\right)}
134+
\newcommand{\xno}[1]{x_{#1}}
135+
\newcommand{\Xno}[1]{X_{(#1)}}
136+
\newcommand{\yno}[1]{y_{#1}}
137+
\newcommand{\Yno}[1]{Y_{(#1)}}
138+
\newcommand{\xdno}[1]{\bm{x}_{#1}}
139+
140+
% FEniCS commands
141+
\newcommand{\dX}{\, \mathrm{d}X}
142+
\newcommand{\dx}{\, \mathrm{d}x}
143+
\newcommand{\ds}{\, \mathrm{d}s}
144+
\newcommand{\Real}{\mathbb{R}}
145+
\newcommand{\Integerp}{\mathbb{N}}
146+
\newcommand{\Integer}{\mathbb{Z}}
147+
148+
# Quarto variables (replacement for Mako variables)
149+
# These can be referenced as {{< var name >}} in documents
150+
src: "https://github.com/hplgit/fdm-book/tree/master/src"
151+
src_vib: "https://github.com/hplgit/fdm-book/tree/master/src/vib"
152+
src_wave: "https://github.com/hplgit/fdm-book/tree/master/src/wave"
153+
src_diffu: "https://github.com/hplgit/fdm-book/tree/master/src/diffu"
154+
src_nonlin: "https://github.com/hplgit/fdm-book/tree/master/src/nonlin"
155+
src_trunc: "https://github.com/hplgit/fdm-book/tree/master/src/trunc"
156+
src_advec: "https://github.com/hplgit/fdm-book/tree/master/src/advec"
157+
src_formulas: "https://github.com/hplgit/fdm-book/tree/master/src/formulas"
158+
src_softeng2: "https://github.com/hplgit/fdm-book/tree/master/src/softeng2"
159+
160+
crossref:
161+
eq-prefix: ""
162+
fig-prefix: "Figure"
163+
tbl-prefix: "Table"
164+
sec-prefix: "Section"
165+
chapters: true

0 commit comments

Comments
 (0)