From c50dcc8495c6fa0a2e489124244195d517e7ca8c Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 2 Feb 2026 14:10:10 -0600 Subject: [PATCH 1/7] allow documentation to fit browser width --- docs/source_docs/_static/theme_overrides.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source_docs/_static/theme_overrides.css b/docs/source_docs/_static/theme_overrides.css index 75a87ae..282078d 100644 --- a/docs/source_docs/_static/theme_overrides.css +++ b/docs/source_docs/_static/theme_overrides.css @@ -15,3 +15,7 @@ .eqno { float: right; } + +.wy-nav-content { + max-width: none; +} -- GitLab From 9bb8da6b31db36423e1e1b039515262f9bacde87 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 2 Feb 2026 14:10:35 -0600 Subject: [PATCH 2/7] latex options --- docs/source_docs/conf.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/source_docs/conf.py b/docs/source_docs/conf.py index f4b5faa..d0173ca 100644 --- a/docs/source_docs/conf.py +++ b/docs/source_docs/conf.py @@ -194,3 +194,25 @@ texinfo_documents = [ author, 'MFIX-Exa Team', "MFIX-Exa, it's MFiX... but now with more Exa!", 'Miscellaneous Aardvark'), ] + +latex_engine = 'xelatex' + +latex_elements = { + 'geometry': r'\usepackage[margin=0.75in]{geometry}', + 'preamble': r''' +% Increase minimum column width +\setlength{\tymin}{120pt} +% Allow text to wrap better in table cells +\usepackage{ragged2e} +\RaggedRight +% More vertical space in table rows +\renewcommand{\arraystretch}{1.2} +% Fix for tables with problematic content +\usepackage{ltablex} +\usepackage{tabularx} +% Prevent overfull hbox in tables +\setlength{\emergencystretch}{3em} +''', +} +# Use longtable for better page breaks and wrapping +latex_table_style = ['longtable', 'colorrows'] -- GitLab From fe183f70b632af78cd3c4ccbe7217372f13a4c15 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 2 Feb 2026 14:10:49 -0600 Subject: [PATCH 3/7] align -> aligned (for PDF output) --- .../references/size_distributions.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source_docs/references/size_distributions.rst b/docs/source_docs/references/size_distributions.rst index c051ddf..4cb49e9 100644 --- a/docs/source_docs/references/size_distributions.rst +++ b/docs/source_docs/references/size_distributions.rst @@ -233,20 +233,20 @@ The mean of this distribution is computed as .. math:: :label: eq_normal_dist_FN_to_FV_mean - \begin{align} + \begin{aligned} \mu_V =& \frac{ \int_{-\infty}^{\infty} x \tilde{f}_X^V(x) dx }{\int_{-\infty}^{\infty} \tilde{f}_X^V(x) dx } \\[10pt] =& \frac{3\sigma_N^4 + 6\sigma_N^2\mu_N^2 + \mu_N^4}{3\sigma_N^2 \mu_N + \mu_N^3} - \end{align} + \end{aligned} and the variance is given by .. math:: :label: eq_normal_dist_FN_to_FV_variance - \begin{align} + \begin{aligned} \sigma^2_V =& \frac{ \int_{-\infty}^{\infty} (x - \mu_V)^2 \tilde{f}_X^V(x) dx }{\int_{-\infty}^{\infty} \tilde{f}_X^V(x) dx } \\[10pt] =& \frac{3\sigma_N^4 (3\mu_N + 2b) + \sigma^2(\mu_N^3 + 6\mu_N^2 b + 3\mu_Nb^2)+\mu_N^3 b^2}{3\sigma_N^2 \mu_N + \mu_N^3} - \end{align} + \end{aligned} where :math:`b = (\mu_N - \mu_V)`. Because the volume-weighted distribution is normally distributed, the computed mean and variance can be substituted directly into :eq:`eq_normal_dist`. @@ -264,10 +264,10 @@ mean and standard deviation, :math:`\mu_V` and :math:`\sigma_V`, by solving the .. math:: - \begin{align} + \begin{aligned} f_1(\mu_N,\sigma_N) &= \left( 3\sigma_N^4 + 6\sigma_N^2\mu_N^2 + \mu_N^4 \right) - \mu_V \left( 3\sigma_N^2 \mu_N + \mu_N^3 \right) = 0 \\ f_2(\mu_N,\sigma_N) &= \left(3\sigma_N^4 (3\mu_N + 2b) + \sigma^2(\mu_N^3 + 6\mu_N^2 b + 3\mu_Nb^2)+\mu_N^3 b^2\right) - \sigma^2_V \left( 3\sigma_N^2 \mu_N + \mu_N^3 \right) = 0 - \end{align} + \end{aligned} This system is solved using the homotopy method outlined in :cite:t:`Burden10`. To ensure rapid convergence, initial guesses for :math:`\mu_N` and :math:`\sigma_N` are calculated from the density function created by dividing :eq:`eq_normal_dist` by :math:`x^3` @@ -288,11 +288,11 @@ are found by setting the derivative of :eq:`eq_normal_dist_FV_to_FN_initial_expr .. math:: :label: eq_normal_dist_FV_to_FN_discrete_values - \begin{align} + \begin{aligned} x_{\mathrm{min}} \; =& \; \left( \mu_V - \sqrt{\mu_V^2 -12\sigma_V^2}\right)/2 \\ x_{\mathrm{mid}} \; =& \; \left(\mu_V + \sqrt{\mu_V^2 -12\sigma_V^2}\right)/2 \\ x_{\mathrm{max}} \; =& \; 2x_{\mathrm{mid}} - x_{\mathrm{min}} - \end{align} + \end{aligned} .. _fig_normal-dist-pdf-approx_FN: @@ -464,10 +464,10 @@ while the parameter :math:`\mu` is computed directly from the other distribution .. math:: - \begin{align} + \begin{aligned} \mu_V =& \mu_N + 3.0\sigma^2 \\[10pt] \mu_N =& \mu_V - 3.0\sigma^2 - \end{align} + \end{aligned} .. rubric:: Sampling a log-normal distribution -- GitLab From c891390c7e8353af4c343f33f8f5693a667865cf Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 2 Feb 2026 14:11:03 -0600 Subject: [PATCH 4/7] fix equation (for PDF output) --- docs/source_docs/user_guide/inputs/chemical_reactions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index 4289016..a81e6bf 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -4,7 +4,7 @@ Defining chemical reactions =========================== -.. |tol_eq| replace:: :math:`\left|\sum\text{products - \sum\text{reactants}\right| < \text{tolerance}` +.. |tol_eq| replace:: :math:`\left|\sum \mathrm{products} - \sum \mathrm{reactants}\right| < \mathrm{tolerance}` The following inputs are defined using the prefix ``chemistry``: -- GitLab From 9f518033b8bc462f5da46590d45a84db537702a7 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 2 Feb 2026 14:11:15 -0600 Subject: [PATCH 5/7] escape underscore (for PDF output) --- docs/source_docs/user_guide/inputs/mesh_and_gridding.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/mesh_and_gridding.rst b/docs/source_docs/user_guide/inputs/mesh_and_gridding.rst index a32719e..c5c1bf0 100644 --- a/docs/source_docs/user_guide/inputs/mesh_and_gridding.rst +++ b/docs/source_docs/user_guide/inputs/mesh_and_gridding.rst @@ -27,9 +27,9 @@ number of cells. The mesh spacing is required to be the same in all directions: .. math:: - \frac{\text{prob_hi[0] - prob_lo[0]}}{\text{n_cell[0]}} - = \frac{\text{prob_hi[1] - prob_lo[1]}}{\text{n_cell[1]}} - = \frac{\text{prob_hi[2] - prob_lo[2]}}{\text{n_cell[2]}} + \frac{\text{prob\_hi[0] - prob\_lo[0]}}{\text{n\_cell[0]}} + = \frac{\text{prob\_hi[1] - prob\_lo[1]}}{\text{n\_cell[1]}} + = \frac{\text{prob\_hi[2] - prob\_lo[2]}}{\text{n\_cell[2]}} The inputs for defining the mesh for a single-level simulation are demonstrated in the -- GitLab From 490d808dc4c051d5748efd58f7b435150a1b3fa6 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 2 Feb 2026 14:11:26 -0600 Subject: [PATCH 6/7] remove split from equation (for PDF output) --- docs/source_docs/user_guide/inputs/model_options.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source_docs/user_guide/inputs/model_options.rst b/docs/source_docs/user_guide/inputs/model_options.rst index 01c0e89..b92e985 100644 --- a/docs/source_docs/user_guide/inputs/model_options.rst +++ b/docs/source_docs/user_guide/inputs/model_options.rst @@ -307,7 +307,7 @@ The following input is defined using the prefix ``mfix.drag``: .. |VM_Zuber_Eq| replace:: :math:`C_{p,vm} = (\frac{1}{2})\frac{(1+2\varepsilon_p)}{(1-\varepsilon_p)}` -.. |VM_Nijssen_Eq| replace:: :math:`\begin{split}C_{p,vm} &= C_{0,vm} \\ &+ \sum_{k=1}^3 \left\{ \left[ a_{k,0} + a_{k,1} \ln \left( \frac{\rho_p}{\rho_f} \right) \right] \varepsilon_p^k \right\}\end{split}` +.. |VM_Nijssen_Eq| replace:: :math:`C_{p,vm} = C_{0,vm} + \sum_{k=1}^3 \left\{ \left[ a_{k,0} + a_{k,1} \ln \left( \frac{\rho_p}{\rho_f} \right) \right] \varepsilon_p^k \right\}` +--------------------------+-----------------------------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | -- GitLab From 14e57f0efc792570a8cac1efacce9305071f8f30 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 2 Feb 2026 14:27:16 -0600 Subject: [PATCH 7/7] add instructions for PDF --- README.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 8a510fe..3f50cfa 100644 --- a/README.md +++ b/README.md @@ -34,16 +34,33 @@ can be built locally by: > pip install sphinx sphinx_rtd_theme sphinx-tabs sphinxcontrib-bibtex ``` -2. Build the documentation: +2. Build the documentation (HTML): ```shell -> mkdir build -> sphinx-build -b html docs/source_docs/ build +$ make # note, "make html" also works ``` -The HTML pages will now be located in the `build` directory. Open the -`index.html` with your favorite browser: +The HTML pages will be located in the `build/html` directory. +Open the `index.html` with your favorite browser: ```shell -> firefox build/index.html +$ firefox build/html/index.html +``` + +3. Build the documentation (PDF): + +You will need xetex. You should be able to get this from your +distribution's package repository. On Ubuntu something like +``sudo apt-get install texlive-xetex`` should do the trick. +More info at https://www.tug.org/texlive/ + +```shell +$ make pdf +``` + +The output file `mfix.pdf` will be in `build/latex` + +4. Cleaning up: +``` shell +$ make clean ``` -- GitLab