Skip to content

Added comments suggesting documentation improvements. #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vvvvalvalval wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Added comments suggesting documentation improvements. #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions org/pyretechnics.org
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,31 @@ operating system. See [[file:../README.md][README.md]] for more details.
[fn:lit-prog-wikipedia] https://en.wikipedia.org/wiki/Literate_programming
[fn:guix-website] https://guix.gnu.org

* FIXME missing sections

A high-level overview.
Must describe the main choices and tradeoffs of kinematic models like Pyretechnics.
Right now the documentation is mostly a sequence of technical rabbit holes
with no overarching narrative, ordered in a way that arguably makes more sense for compilers than humans;
this makes for good reference material, but we need to help readers find their way into it,
and make it easy for them to make sense of Pyretechnics without going into every detail of the code.

A how-to section for the most common use cases.
Right now, users find themselves having to scan the whole Table of Contents,
most of which is implementation details they won't care about.

A section that explains the calculation of front-normal spread rates
and $d\varphi/dt$, as is done in =elliptical-wavelets.pdf=.
This is needed because it's a nontrivial piece of math, and one that's novel compared to ELMFIRE.

A section explaining 2nd-order Runge-Kutta integration and time-step calculation.

A section explaining narrow-band tracking.

Validation / verification experiments.



* Data Model
:PROPERTIES:
:CUSTOM_ID: data-model
Expand Down Expand Up @@ -3876,6 +3901,21 @@ def calc_surface_fire_behavior_max(surface_fire_min : FireBehaviorMin,
:CUSTOM_ID: surface-fire-behavior-in-any-direction
:END:

FIXME this section is incorrect, because the spread rates it computes are not front-normal spread rates.
$R_s(\omega)$ as computed here is a 'radial' rate of spread; it's interesting in some ways,
but not adequate for computing the fireline intensity.
What's needed for computing the fireline intensity is the front-normal spread rate,
i.e. the velocity at which the fire front advances in the direction perpendicular to itself.
The correct formula for this is:

\begin{equation}
R_s(\omega) = \frac{V_H - V_B}{2} \cos(\omega) + V_F \sqrt{1 + \left(\left(\frac{L}{W}\right)^2 - 1\right)\cos(\omega)^2}
\end{equation}

in which $V_H, V_B, V_F$ are the heading, backing, and flanking spread rates, respectively.
Note that $V_F = (V_H + V_B)/(2 (L/W))$.


Once we have calculated the maximum surface fire behavior values
associated with a head fire, we can use the elliptical eccentricity
$E$ to project the maximum spread rate $R_s$ and maximum fireline
Expand Down Expand Up @@ -8408,6 +8448,10 @@ else:
:CUSTOM_ID: the-$\phi$-field
:END:

FIXME I would suggest to mention that the level-set method consists of
representing the fire front as the zero level set of $\phi$,
and more precisely the burned region as $\phi \leq 0$.

In this model, a continuous field called $\phi$ fills the simulation
space and is used to track the progression of the fire front through
space and time. Within Pyretechnics, the $\phi$ field is discretized
Expand All @@ -8426,6 +8470,9 @@ set to -1 and the remaining cells will have the value 1.
:CUSTOM_ID: fire-front-normal-vector
:END:

FIXME this section is obsolete. We don't need to compute the normal vector or azimuth.
The code itself documents it as unused.

In this fire spread algorithm, the fire front only propagates normal
to itself. Given a $\phi$ raster, we can calculate the normal vector to
the $\phi$ field by using the following formula:
Expand Down Expand Up @@ -8568,6 +8615,10 @@ the following sections as $U$ with spatial components $U_x$ and $U_y$.
:CUSTOM_ID: numerical-solution-of-the-$\phi$-field-equation
:END:

FIXME this section should really be called "flux-limiting".
It's far from covering all there is to say about the numerical solution.
It should be presented as yielding a corrective multiplier on $(d \varphi / dt)$.

In order to evolve the $\phi$ field through time and space, we must
solve the following hyperbolic differential equation for the scalar
variable $\phi$.
Expand Down Expand Up @@ -8958,6 +9009,9 @@ Surface and Crown Fire Behavior]]) is returned. If no crown fire occurs,
the surface fire behavior in the direction of the 3D $\phi$ gradient
is returned.

FIXME this code snippet has nothing to do with the above paragraph,
it's just plumbing related to inputs and outputs.

#+NAME: burn-cell-toward-phi-gradient
#+begin_src python
# TODO: Turn this into a struct once its methods have been removed
Expand Down Expand Up @@ -9519,6 +9573,7 @@ def identify_tracked_cells(frontier_cells: set,
:CUSTOM_ID: spread-phi-field
:END:

FIXME this might be the right place to describe the elliptical wavelets math.
# TODO: Include Val's proof for late integration of the limited and unlimited phi gradients in dphi/dt.

$\hat{\nabla} \varphi \cdot U = (\hat{\nabla} \varphi \cdot \frac{\ddot{\nabla} \varphi}{|\ddot{\nabla} \varphi|}) (\frac{\ddot{\nabla} \varphi}{|\ddot{\nabla} \varphi|}\cdot U) = (\hat{\nabla} \varphi \cdot \frac{\ddot{\nabla} \varphi}{|\ddot{\nabla} \varphi|^2}) (\ddot{\nabla} \varphi \cdot U)$
Expand Down