Skip to content

Commit

Permalink
deploy: 34c90b4
Browse files Browse the repository at this point in the history
  • Loading branch information
@visr
visr committed Feb 23, 2024
1 parent 2e8abe4 commit 1a93863
Show file tree
Hide file tree
Showing 8 changed files with 227 additions and 224 deletions.
358 changes: 181 additions & 177 deletions build/index.html
View file

Large diffs are not rendered by default.

32 changes: 16 additions & 16 deletions core/allocation.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -623,7 +623,7 @@ <h1 data-number="5"><span class="header-section-number">5</span> Solving the all
<section id="example" class="level2" data-number="5.1">
<h2 data-number="5.1" class="anchored" data-anchor-id="example"><span class="header-section-number">5.1</span> Example</h2>
<p>The following is an example of an optimization problem for the example shown <a href="../python/examples.html#model-with-allocation">here</a>:</p>
<div id="96477f23" class="cell" data-execution_count="1">
<div id="b75298ca" class="cell" data-execution_count="1">
<details class="code-fold">
<summary>Code</summary>
<div class="sourceCode cell-code" id="cb1"><pre class="sourceCode julia code-with-copy"><code class="sourceCode julia"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="im">using</span> <span class="bu">Ribasim</span></span>
Expand All @@ -648,45 +648,45 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="example"><span class="hea
<span id="cb1-20"><a href="#cb1-20" aria-hidden="true" tabindex="-1"></a><span class="fu">println</span>(p.allocation.allocation_models[<span class="fl">1</span>].problem)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</details>
<div class="cell-output cell-output-stdout">
<pre><code>Min F_abs_user[User #3] + F_abs_user[User #13] + F_abs_user[User #6] + F_abs_basin[Basin #12] + F_abs_basin[Basin #5] + F_abs_basin[Basin #2]
<pre><code>Min F_abs_user[User #13] + F_abs_user[User #6] + F_abs_user[User #3] + F_abs_basin[Basin #12] + F_abs_basin[Basin #2] + F_abs_basin[Basin #5]
Subject to
flow_conservation[Basin #12] : F[(Basin #12, User #13)] - F[(TabulatedRatingCurve #7, Basin #12)] + F_basin_in[Basin #12] - F_basin_out[Basin #12] = 0
flow_conservation[Basin #12] : -F[(TabulatedRatingCurve #7, Basin #12)] + F[(Basin #12, User #13)] + F_basin_in[Basin #12] - F_basin_out[Basin #12] = 0
flow_conservation[Basin #2] : -F[(FlowBoundary #1, Basin #2)] + F[(Basin #2, User #3)] + F[(Basin #2, Basin #5)] - F[(Basin #5, Basin #2)] + F_basin_in[Basin #2] - F_basin_out[Basin #2] = 0
flow_conservation[Basin #5] : F[(Basin #5, User #6)] + F[(Basin #5, TabulatedRatingCurve #7)] - F[(Basin #2, Basin #5)] + F[(Basin #5, Basin #2)] + F_basin_in[Basin #5] - F_basin_out[Basin #5] = 0
flow_conservation[Basin #2] : F[(Basin #2, Basin #5)] + F[(Basin #2, User #3)] - F[(Basin #5, Basin #2)] - F[(FlowBoundary #1, Basin #2)] + F_basin_in[Basin #2] - F_basin_out[Basin #2] = 0
abs_positive_user[User #3] : -F[(Basin #2, User #3)] + F_abs_user[User #3] ≥ 0
abs_positive_user[User #13] : -F[(Basin #12, User #13)] + F_abs_user[User #13] ≥ 0
abs_positive_user[User #6] : -F[(Basin #5, User #6)] + F_abs_user[User #6] ≥ -1.5
abs_negative_user[User #3] : F[(Basin #2, User #3)] + F_abs_user[User #3] ≥ 0
abs_positive_user[User #3] : -F[(Basin #2, User #3)] + F_abs_user[User #3] ≥ 0
abs_negative_user[User #13] : F[(Basin #12, User #13)] + F_abs_user[User #13] ≥ 0
abs_negative_user[User #6] : F[(Basin #5, User #6)] + F_abs_user[User #6] ≥ 1.5
abs_negative_user[User #3] : F[(Basin #2, User #3)] + F_abs_user[User #3] ≥ 0
abs_positive_basin[Basin #12] : -F_basin_in[Basin #12] + F_abs_basin[Basin #12] ≥ 0
abs_positive_basin[Basin #5] : -F_basin_in[Basin #5] + F_abs_basin[Basin #5] ≥ 0
abs_positive_basin[Basin #2] : -F_basin_in[Basin #2] + F_abs_basin[Basin #2] ≥ 0
abs_positive_basin[Basin #5] : -F_basin_in[Basin #5] + F_abs_basin[Basin #5] ≥ 0
abs_negative_basin[Basin #12] : F_basin_in[Basin #12] + F_abs_basin[Basin #12] ≥ 0
abs_negative_basin[Basin #5] : F_basin_in[Basin #5] + F_abs_basin[Basin #5] ≥ 0
abs_negative_basin[Basin #2] : F_basin_in[Basin #2] + F_abs_basin[Basin #2] ≥ 0
abs_negative_basin[Basin #5] : F_basin_in[Basin #5] + F_abs_basin[Basin #5] ≥ 0
source[(FlowBoundary #1, Basin #2)] : F[(FlowBoundary #1, Basin #2)] ≤ 1
return_flow[User #13] : F[(User #13, Terminal #10)] ≤ 0
fractional_flow[(TabulatedRatingCurve #7, Basin #12)] : -0.4 F[(Basin #5, TabulatedRatingCurve #7)] + F[(TabulatedRatingCurve #7, Basin #12)] ≤ 0
basin_outflow[Basin #12] : F_basin_out[Basin #12] ≤ 0
basin_outflow[Basin #5] : F_basin_out[Basin #5] ≤ 0
basin_outflow[Basin #2] : F_basin_out[Basin #2] ≤ 0
basin_outflow[Basin #5] : F_basin_out[Basin #5] ≤ 0
F[(FlowBoundary #1, Basin #2)] ≥ 0
F[(Basin #5, User #6)] ≥ 0
F[(TabulatedRatingCurve #7, Terminal #10)] ≥ 0
F[(Basin #5, TabulatedRatingCurve #7)] ≥ 0
F[(Basin #2, Basin #5)] ≥ 0
F[(TabulatedRatingCurve #7, Terminal #10)] ≥ 0
F[(TabulatedRatingCurve #7, Basin #12)] ≥ 0
F[(Basin #2, User #3)] ≥ 0
F[(Basin #12, User #13)] ≥ 0
F[(User #13, Terminal #10)] ≥ 0
F[(Basin #12, User #13)] ≥ 0
F[(Basin #2, Basin #5)] ≥ 0
F[(Basin #5, Basin #2)] ≥ 0
F[(FlowBoundary #1, Basin #2)] ≥ 0
F[(TabulatedRatingCurve #7, Basin #12)] ≥ 0
F_basin_in[Basin #12] ≥ 0
F_basin_in[Basin #5] ≥ 0
F_basin_in[Basin #2] ≥ 0
F_basin_in[Basin #5] ≥ 0
F_basin_out[Basin #12] ≥ 0
F_basin_out[Basin #5] ≥ 0
F_basin_out[Basin #2] ≥ 0
F_basin_out[Basin #5] ≥ 0
</code></pre>
</div>
</div>
Expand Down
2 changes: 1 addition & 1 deletion core/equations.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -427,7 +427,7 @@ <h2 data-number="2.1" class="anchored" data-anchor-id="sec-reduction_factor"><sp
\end{cases}
\end{align}\]</span></p>
<p>Here <span class="math inline">\(p &gt; 0\)</span> is the threshold value which determines the interval <span class="math inline">\([0,p]\)</span> of the smooth transition between <span class="math inline">\(0\)</span> and <span class="math inline">\(1\)</span>, see the plot below.</p>
<div id="0e1536b0" class="cell" data-execution_count="1">
<div id="558333d1" class="cell" data-execution_count="1">
<details class="code-fold">
<summary>Code</summary>
<div class="sourceCode cell-code" id="cb1"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="im">import</span> numpy <span class="im">as</span> np</span>
Expand Down
45 changes: 22 additions & 23 deletions core/usage.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -399,31 +399,30 @@ <h1 data-number="1"><span class="header-section-number">1</span> Configuration f
<span id="cb2-21"><a href="#cb2-21" aria-hidden="true" tabindex="-1"></a><span class="kw">[solver]</span></span>
<span id="cb2-22"><a href="#cb2-22" aria-hidden="true" tabindex="-1"></a><span class="dt">algorithm</span> <span class="op">=</span> <span class="st">"QNDF"</span> <span class="co"># optional, default "QNDF"</span></span>
<span id="cb2-23"><a href="#cb2-23" aria-hidden="true" tabindex="-1"></a><span class="dt">saveat</span> <span class="op">=</span> <span class="dv">86400</span> <span class="co"># optional, default 86400, 0 saves every timestep, inf saves only at start- and endtime</span></span>
<span id="cb2-24"><a href="#cb2-24" aria-hidden="true" tabindex="-1"></a><span class="dt">adaptive</span> <span class="op">=</span> <span class="cn">true</span> <span class="co"># optional, default true</span></span>
<span id="cb2-25"><a href="#cb2-25" aria-hidden="true" tabindex="-1"></a><span class="dt">dt</span> <span class="op">=</span> <span class="fl">0.0</span> <span class="co"># optional when adaptive = true, default automatically determined</span></span>
<span id="cb2-26"><a href="#cb2-26" aria-hidden="true" tabindex="-1"></a><span class="dt">dtmin</span> <span class="op">=</span> <span class="fl">0.0</span> <span class="co"># optional, default 0.0</span></span>
<span id="cb2-27"><a href="#cb2-27" aria-hidden="true" tabindex="-1"></a><span class="dt">dtmax</span> <span class="op">=</span> <span class="fl">0.0</span> <span class="co"># optional, default length of simulation</span></span>
<span id="cb2-28"><a href="#cb2-28" aria-hidden="true" tabindex="-1"></a><span class="dt">force_dtmin</span> <span class="op">=</span> <span class="cn">false</span> <span class="co"># optional, default false</span></span>
<span id="cb2-29"><a href="#cb2-29" aria-hidden="true" tabindex="-1"></a><span class="dt">abstol</span> <span class="op">=</span> <span class="fl">1e-6</span> <span class="co"># optional, default 1e-6</span></span>
<span id="cb2-30"><a href="#cb2-30" aria-hidden="true" tabindex="-1"></a><span class="dt">reltol</span> <span class="op">=</span> <span class="fl">1e-5</span> <span class="co"># optional, default 1e-5</span></span>
<span id="cb2-31"><a href="#cb2-31" aria-hidden="true" tabindex="-1"></a><span class="dt">maxiters</span> <span class="op">=</span> <span class="fl">1e9</span> <span class="co"># optional, default 1e9</span></span>
<span id="cb2-32"><a href="#cb2-32" aria-hidden="true" tabindex="-1"></a><span class="dt">sparse</span> <span class="op">=</span> <span class="cn">true</span> <span class="co"># optional, default true</span></span>
<span id="cb2-33"><a href="#cb2-33" aria-hidden="true" tabindex="-1"></a><span class="dt">autodiff</span> <span class="op">=</span> <span class="cn">true</span> <span class="co"># optional, default true</span></span>
<span id="cb2-34"><a href="#cb2-34" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-35"><a href="#cb2-35" aria-hidden="true" tabindex="-1"></a><span class="kw">[logging]</span></span>
<span id="cb2-36"><a href="#cb2-36" aria-hidden="true" tabindex="-1"></a><span class="co"># defines the logging level of Ribasim</span></span>
<span id="cb2-37"><a href="#cb2-37" aria-hidden="true" tabindex="-1"></a><span class="dt">verbosity</span> <span class="op">=</span> <span class="st">"info"</span> <span class="co"># optional, default "info", can otherwise be "debug", "warn" or "error"</span></span>
<span id="cb2-38"><a href="#cb2-38" aria-hidden="true" tabindex="-1"></a><span class="dt">timing</span> <span class="op">=</span> <span class="cn">false</span> <span class="co"># optional, whether to log debug timing statements</span></span>
<span id="cb2-39"><a href="#cb2-39" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-40"><a href="#cb2-40" aria-hidden="true" tabindex="-1"></a><span class="kw">[results]</span></span>
<span id="cb2-41"><a href="#cb2-41" aria-hidden="true" tabindex="-1"></a><span class="co"># These results files are always written</span></span>
<span id="cb2-42"><a href="#cb2-42" aria-hidden="true" tabindex="-1"></a><span class="dt">compression</span> <span class="op">=</span> <span class="cn">true</span> <span class="co"># optional, default true, using zstd compression</span></span>
<span id="cb2-43"><a href="#cb2-43" aria-hidden="true" tabindex="-1"></a><span class="dt">compression_level</span> <span class="op">=</span> <span class="dv">6</span> <span class="co"># optional, default 6</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<span id="cb2-24"><a href="#cb2-24" aria-hidden="true" tabindex="-1"></a><span class="dt">dt</span> <span class="op">=</span> <span class="fl">60.0</span> <span class="co"># optional, remove for adaptive time stepping</span></span>
<span id="cb2-25"><a href="#cb2-25" aria-hidden="true" tabindex="-1"></a><span class="dt">dtmin</span> <span class="op">=</span> <span class="fl">0.0</span> <span class="co"># optional, default 0.0</span></span>
<span id="cb2-26"><a href="#cb2-26" aria-hidden="true" tabindex="-1"></a><span class="dt">dtmax</span> <span class="op">=</span> <span class="fl">0.0</span> <span class="co"># optional, default length of simulation</span></span>
<span id="cb2-27"><a href="#cb2-27" aria-hidden="true" tabindex="-1"></a><span class="dt">force_dtmin</span> <span class="op">=</span> <span class="cn">false</span> <span class="co"># optional, default false</span></span>
<span id="cb2-28"><a href="#cb2-28" aria-hidden="true" tabindex="-1"></a><span class="dt">abstol</span> <span class="op">=</span> <span class="fl">1e-6</span> <span class="co"># optional, default 1e-6</span></span>
<span id="cb2-29"><a href="#cb2-29" aria-hidden="true" tabindex="-1"></a><span class="dt">reltol</span> <span class="op">=</span> <span class="fl">1e-5</span> <span class="co"># optional, default 1e-5</span></span>
<span id="cb2-30"><a href="#cb2-30" aria-hidden="true" tabindex="-1"></a><span class="dt">maxiters</span> <span class="op">=</span> <span class="fl">1e9</span> <span class="co"># optional, default 1e9</span></span>
<span id="cb2-31"><a href="#cb2-31" aria-hidden="true" tabindex="-1"></a><span class="dt">sparse</span> <span class="op">=</span> <span class="cn">true</span> <span class="co"># optional, default true</span></span>
<span id="cb2-32"><a href="#cb2-32" aria-hidden="true" tabindex="-1"></a><span class="dt">autodiff</span> <span class="op">=</span> <span class="cn">true</span> <span class="co"># optional, default true</span></span>
<span id="cb2-33"><a href="#cb2-33" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-34"><a href="#cb2-34" aria-hidden="true" tabindex="-1"></a><span class="kw">[logging]</span></span>
<span id="cb2-35"><a href="#cb2-35" aria-hidden="true" tabindex="-1"></a><span class="co"># defines the logging level of Ribasim</span></span>
<span id="cb2-36"><a href="#cb2-36" aria-hidden="true" tabindex="-1"></a><span class="dt">verbosity</span> <span class="op">=</span> <span class="st">"info"</span> <span class="co"># optional, default "info", can otherwise be "debug", "warn" or "error"</span></span>
<span id="cb2-37"><a href="#cb2-37" aria-hidden="true" tabindex="-1"></a><span class="dt">timing</span> <span class="op">=</span> <span class="cn">false</span> <span class="co"># optional, whether to log debug timing statements</span></span>
<span id="cb2-38"><a href="#cb2-38" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-39"><a href="#cb2-39" aria-hidden="true" tabindex="-1"></a><span class="kw">[results]</span></span>
<span id="cb2-40"><a href="#cb2-40" aria-hidden="true" tabindex="-1"></a><span class="co"># These results files are always written</span></span>
<span id="cb2-41"><a href="#cb2-41" aria-hidden="true" tabindex="-1"></a><span class="dt">compression</span> <span class="op">=</span> <span class="cn">true</span> <span class="co"># optional, default true, using zstd compression</span></span>
<span id="cb2-42"><a href="#cb2-42" aria-hidden="true" tabindex="-1"></a><span class="dt">compression_level</span> <span class="op">=</span> <span class="dv">6</span> <span class="co"># optional, default 6</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<section id="sec-solver-settings" class="level2" data-number="1.1">
<h2 data-number="1.1" class="anchored" data-anchor-id="sec-solver-settings"><span class="header-section-number">1.1</span> Solver settings</h2>
<p>The solver section in the configuration file is entirely optional, since we aim to use defaults that will generally work well. Common reasons to modify the solver settings are to adjust the calculation or result stepsizes: <code>adaptive</code>, <code>dt</code>, and <code>saveat</code>. If your model does not converge, or your performance is lower than expected, it can help to adjust other solver settings as well.</p>
<p>The default solver <code>algorithm = "QNDF"</code>, which is a multistep method similar to Matlab’s <code>ode15s</code> <span class="citation" data-cites="shampine1997matlab">(<a href="#ref-shampine1997matlab" role="doc-biblioref">Shampine and Reichelt 1997</a>)</span>. It is an implicit method that supports the default <code>adaptive = true</code> timestepping. The full list of available solvers is: <code>QNDF</code>, <code>Rosenbrock23</code>, <code>TRBDF2</code>, <code>Rodas5</code>, <code>KenCarp4</code>, <code>Tsit5</code>, <code>RK4</code>, <code>ImplicitEuler</code>, <code>Euler</code>. Information on the solver algorithms can be found on the <a href="https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/">ODE solvers page</a>.</p>
<p>The <code>dt</code> controls the stepsize. When <code>adaptive = true</code>, <code>dt</code> only applies to the initial stepsize, and by default it is automatically determined. When <code>adaptive = false</code> a suitable <code>dt</code> must always be provided. The value is in seconds, so <code>dt = 3600.0</code> corresponds to an hourly timestep. When <code>adaptive = true</code>, <code>dtmin</code> and <code>dtmax</code> control the minimum and maximum allowed <code>dt</code>. If a smaller <code>dt</code> than <code>dtmin</code> is needed to meet the set error tolerances, the simulation stops, unless <code>force_dtmin</code> is set to <code>true</code>. <code>force_dtmin</code> is off by default to ensure an accurate solution.</p>
<p>The solver section in the configuration file is entirely optional, since we aim to use defaults that will generally work well. Common reasons to modify the solver settings are to adjust the calculation or result stepsizes: <code>dt</code>, and <code>saveat</code>. If your model does not converge, or your performance is lower than expected, it can help to adjust other solver settings as well.</p>
<p>The default solver <code>algorithm = "QNDF"</code>, which is a multistep method similar to Matlab’s <code>ode15s</code> <span class="citation" data-cites="shampine1997matlab">(<a href="#ref-shampine1997matlab" role="doc-biblioref">Shampine and Reichelt 1997</a>)</span>. It is an implicit method that supports the default adaptive timestepping. The full list of available solvers is: <code>QNDF</code>, <code>Rosenbrock23</code>, <code>TRBDF2</code>, <code>Rodas5</code>, <code>KenCarp4</code>, <code>Tsit5</code>, <code>RK4</code>, <code>ImplicitEuler</code>, <code>Euler</code>. Information on the solver algorithms can be found on the <a href="https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/">ODE solvers page</a>.</p>
<p>By default Ribasim uses adaptive timestepping, though not all algorithms support adaptive timestepping. To use fixed timesteps, provide a timestep size in seconds; <code>dt = 3600.0</code> corresponds to an hourly timestep. With adaptive timestepping, <code>dtmin</code> and <code>dtmax</code> control the minimum and maximum allowed <code>dt</code>. If a smaller <code>dt</code> than <code>dtmin</code> is needed to meet the set error tolerances, the simulation stops, unless <code>force_dtmin</code> is set to <code>true</code>. <code>force_dtmin</code> is off by default to ensure an accurate solution.</p>
<p>The default result stepsize, <code>saveat = 86400</code> will save results after every day that passed. The calculation and result stepsize need not be the same. If you wish to save every calculation step, set <code>saveat = 0</code>. If you wish to not save any intermediate steps, set <code>saveat = inf</code>.</p>
<p>The Jacobian matrix provides information about the local sensitivity of the model with respect to changes in the states. For implicit solvers it must be calculated often, which can be expensive to do. There are several methods to do this. By default Ribasim uses a Jacobian derived automatically using <a href="https://juliadiff.org/ForwardDiff.jl/stable/">ForwardDiff.jl</a> with memory management provided by <a href="https://docs.sciml.ai/PreallocationTools/stable/">PreallocationTools.jl</a>. If this is not used by setting <code>autodiff = false</code>, the Jacobian is calculated with a finite difference method, which can be less accurate and more expensive.</p>
<p>By default the Jacobian matrix is a sparse matrix (<code>sparse = true</code>). Since each state typically only depends on a small number of other states, this is generally more efficient, especially for larger models. The sparsity structure is calculated from the network and provided as a Jacobian prototype to the solver. For small or highly connected models it could be faster to use a dense Jacobian matrix instead by setting <code>sparse = false</code>.</p>
Expand Down
Loading

0 comments on commit 1a93863

Please sign in to comment.