diff --git a/README.md b/README.md index 8a510fe77d1928491656f2998948e466db828299..3f50cfa82dd575b325e4f810f4b486a514f867c0 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 ``` diff --git a/docs/source_docs/_static/theme_overrides.css b/docs/source_docs/_static/theme_overrides.css index 75a87ae54e1dcf24ef9863f018befc6ed3b49f84..282078d1d778d4c35201e77d386ecf1957bff1a5 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; +} diff --git a/docs/source_docs/conf.py b/docs/source_docs/conf.py index f4b5faa7ae63ed89cd59d8ef0f2f5efd0b263e7a..d0173caacf4f8d075f5923963874a44e05452a43 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'] diff --git a/docs/source_docs/references/size_distributions.rst b/docs/source_docs/references/size_distributions.rst index c051ddf44cc260aaf34ce401bb2a33b1b9f83506..4cb49e90bb8748b058e2f7f7d98e9a49a3c9fa44 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 diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index 4289016c296dd0c616a0eb9fe93f6f3f36448526..a81e6bf143aa0b2264ac9b1919684036c5f122a1 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``: 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 a32719ea1e52390cb832c4e2982a70c8f7613664..c5c1bf043f11d8a065b9b27522f06899b4513cfb 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 diff --git a/docs/source_docs/user_guide/inputs/model_options.rst b/docs/source_docs/user_guide/inputs/model_options.rst index 01c0e89955c0134a759581a9e68d14e1a70a03ad..b92e9853dc8ab7a993acce841ec7fb989ee67503 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 |