bibun 0.0.0

data/README.md

@@ -0,0 +1,909 @@
+Bibun (微分: differential, derivative). This gem implements Runge-Kutta explicit numerical methods to integrate systems of multiple ordinary differential equations.  For adaptive step size, it currently implements the Dormand-Prince method of order 5(4) which is commonly find as `ode45`, but with additional features and the ability to finely control the integration with plain Ruby.
+
+# Quick feature overview
+
+Instant example for a single differential equation with one variable representing a electrical circuit $\frac{dI}{dt}=15-3*I$
+
+```ruby
+require 'bibun'
+ode = Bibun::DifferentialEquationSystem.new
+ode.add_variable 'current', 'I', rate_function: '15 - 3 * I'
+ode.log_all(4) # logs all variables with 4 decimals
+ode.integrate starting_values: { 'current' => 0, 'time' => 0 }, step_size: 0.02, duration: 1.5
+ode.logger.save_to_file('integration_run.csv')
+```
+
+Using the Dormand Prince method of order (4,5). After the initial step size provided, it adapts it to keep the error below the tolerances provided.
+
+```Ruby
+ode.add_variable 'current', 'I', unit: 'A' rate_function: '15 - 3 * I', atol: 0.001, rtol: 0.001
+ode.integrate starting_values: { 'current' => 0, 'time' => 0 }, step_size: 0.02, duration: 1.5, adaptive: true
+puts ode.current.value
+```
+
+Using an adaptive method, but logging at a specified interval to provide uniform data for graphing (dense output by polynomial interpolation):
+
+```Ruby
+ode.add_variable 'current', 'I', unit: 'A' rate_function: '15 - 3 * I', atol: 0.001, rtol: 0.001
+ode.logger.logging_interval = 0.02
+ode.integrate starting_values: { 'current' => 0, 'time' => 0 }, step_size: 0.02, duration: 1.5, adaptive: true
+puts ode.current.value
+```
+
+Quick example of a differential equation system of two variables, the Lotka Volterra equations with specific parameter values (p and d are the prey and predator variables):
+$$
+\frac{dp}{dt}=0.08p-0.001pd \\
+\frac{dd}{dt}=-0.02d+0.00001pd
+$$
+
+
+```RUby
+require 'bibun'
+
+# lv stands for a Lotka-Volterra system
+
+lv = Bibun::DifferentialEquationSystem.new
+lv.add_variable 'predator', 'd', 'Ecosystem predator', rate_function: '-0.02 * d + 0.00002 * p * d'
+lv.add_variable 'prey', 'p', 'Ecosystem prey', rate_function: '0.08 * p - 0.001 * p * d'
+lv.log_all(2) # Logs all variables with 2 decimals
+lv.integrate starting_values: { 'time' => 0, 'prey' => 1000, 'predator' => 50 }, step_size: 1, duration: 100
+lv.logger.save_to_file('tmp/lotka_volterra_run.csv')
+```
+
+The same example as before, but using parameters rather than hard coded numerical values in the formulas:
+
+```Ruby
+lv = Bibun::DifferentialEquationSystem.new
+lv.add_variable 'predator', 'd', 'Ecosystem predator', rate_function: '-r * d + b * p * d'
+lv.add_variable 'prey', 'p', 'Ecosystem prey', rate_function: 'k * p - a * p * d'
+lv.add_parameter 'prey_growth', 'k', 'Prey growth rate', value: 0.08
+lv.add_parameter 'prey_consumption', 'a', 'Prey consumption parameter', value: 0.001
+lv.add_parameter 'predator_decay', 'r', 'Predator decay rate', value: 0.02
+lv.add_parameter 'predator_proliferation', 'b', 'Predator proliferation parameter', value: 0.00002
+lv.integrate starting_values: { 'time' => 0, 'prey' => 1000, 'predator' => 50 }, step_size: 1, duration: 100
+```
+
+Same example as before, with shortcuts for minimum lines required:
+
+```ruby
+lv = Bibun::DifferentialEquationSystem.new
+lv.add_variables({ 'p' => 'k * p - a * p * d', 'd' => '-r * d + b * p * d' })
+lv.add_parameters({ 'k' => 0.08, 'a' => 0.001, 'r' => 0.02, 'b' => 0.00002 })
+lv.integrate starting_values: { 'time' => 0, 'p' => 1000, 'd' => 50 }, step_size: 1, duration: 100
+```
+
+The same example as before, but tracking the separate contributions from predation and growth / decay:
+
+```Ruby
+lv = Bibun::DifferentialEquationSystem.new
+lv.add_variable 'predator', 'd', 'Ecosystem predator'
+lv.predator.add_rate_term 'Decay', '-r * d'
+lv.predator.add_rate_term 'Predation', 'b * p * d'
+lv.add_variable 'prey', 'p', 'Ecosystem prey'
+lv.prey.add_rate_term 'Growth', 'k * p'
+lv.prey.add_rate_term 'Predation', '- a * p * d'
+lv.add_parameters({ 'k' => 0.08, 'a' => 0.001, 'r' => 0.02, 'b' => 0.00002 })
+lv.log_all(4, with_terms: true) # Shortcut method to adds all variables and their rate terms to the log with 4 decimals
+lv.integrate starting_values: { 'time' => 0, 'prey' => 1000, 'predator' => 50 }, step_size: 1, duration: 100
+# Get array with predator data
+predator_data = lv.logs['predator']
+```
+
+With the same basics, a more complex system: an salt tank receiving two inlets, one outlet and variable water volume, proportional loss rate. The concentration is calculated and tracked from the salt mass and volume variables and each flow contribution is tracked separatedly:
+
+```mermaid
+---
+title: Interface
+---
+flowchart LR
+  tan[Container Tank] -- fo --> out[Outlet]
+  bri[Brine inlet cs] -- fb --> tan
+  spw[Springwater inlet] -- fw --> tan
+  tan -- lV --> los[Loss rate]
+```
+
+```Ruby
+tank = Bibun::DifferentialEquationSystem.new
+tank.time.unit = 'h'
+tank.add_variable 'salt', 'm', 'Mass of salt', 'kg', atol: 0.1
+tank.add_variable 'volume', 'V', 'Tank liquid volume', 'm3', atol: 0.1
+tank.add_parameter 'brine_inlet_flow', 'fb', 'Brine intake', 'm3 / h', value: 5
+tank.add_parameter 'brine_concentration', 'cb', 'Brine concentration', 'kg / m3', value: 35
+tank.add_parameter 'water_inlet_flow', 'fw', 'Water intake', 'm3 / h', value: 2
+tank.add_parameter 'outlet_flow', 'fo', 'Outlet flow', 'm3 / h', value: 6
+tank.add_parameter 'loss_coefficient', 'l', 'Loss coefficient rate', 'h-1', value: 0.25
+tank.volume.add_rate_term 'Outlet loss', '-fo'
+tank.volume.add_rate_term 'Brine inlet gain', 'fb'
+tank.volume.add_rate_term 'Springwater inlet gain', 'fw'
+tank.volume.add_rate_term 'Evaporation', '-l * V'
+tank.salt.add_rate_term 'Brine inlet gain', 'cb * fb'
+tank.salt.add_rate_term 'Outlet loss', '-fo * m / V'
+tank.logger.add_step_state
+tank.logger.add_all(4, with_terms: true)
+tank.logger.add_expression('salt_concentration', 'm / V', 4)
+values = { 'volume' => 50, 'time' => 0, 'salt' => 0 }
+tank.integrate starting_values: values, step_size: 1.fdiv(60), duration: 24, adaptive: true
+puts tank.volume.value # 4.0951 asymptotic towards 4.0
+salt_rate_terms = tank.logs['salt:Brine inlet gain'].zip(tank.logs['salt:Outlet loss'])
+pp salt_rate_terms
+tank.logger.save_to_file('tmp/brine_tank.csv')
+```
+
+#  Gem Description
+
+`Bibun` allows to perform integration runs of systems of differential equations through numerical methods such as the traditional fourth-order Runge-Kutta method or the adaptive Dormand-Prince method similar to ode45 in software packages. `Bibun`, however, runs all on Ruby so it gives you the possibility to achieve complete control and access to its processes through standard object manipulation.
+
+`Bibun` comes with handy features for engineers like the ability to separate the contribution of different rate additive terms of the differential functions, the ability to monitor custom expressions through the run and the ability to store and load integration conditions to and from JSON and TOML files.
+
+This library can handle nonlinear, inhomogeneous and non-autonomous equations, but for the time being it can only handle first-order, explicit systems of differential equations. Convert higher order equations to first order systems before inputting them.
+
+## Intention and spirit of the gem
+
+The gem is primarily intended for engineers to perform integrations with fully powered Ruby objects which can are amentable to further processing and manipulation with further programming. For this, the interface is intended to be extensive and rich.
+
+Math, enthusiasts which like to do quick programming in REPL style or short scripts are acknowledged by provided quick shortcut methods for easy setup in a few lines, but the extensive methods are given greater priority should conflict within both happen.
+
+The gem abides to the Ruby philosophy and provides longer, self describing methods which can be understood naturally at first glance rather than acronyms or abbreviatures and uses object orientation rather than an approach of inputing a function with a long list of primitive arguments and obtaining a literal value.
+
+## Dependencies
+
+This class uses the `keisan`  gem to parse and evaluate mathematical expressions in strings. The main criteria to choose it over the `dentaku` gem was the ability to create multiple instances of `Calculator` each one capable of caching its mathematical expression.
+
+The gem uses the `json`, `tomlib` and `csv` libraries for importing and exporting integration runs.
+
+`Formatador` is used to display a progress bar while doing the integration and for outputting a DES summary.
+
+# General Interface and usage
+
+The outer `DifferentialEquationSystem` class exposes enough general methods to be able to perform straightforward integration runs, but for a completely control over the integration process it is better to understand and access the inner objects that compose it. Below is the basic interface to a differential equation system object:
+
+```mermaid
+---
+title: Interface
+---
+flowchart LR
+  sys[System] --shortcut--> vars[variables]
+  sys --> syms[syms]
+  syms --> vars
+  syms --> pars
+  sys --shortcut--> pars[parameters]
+  vars --> eq[rate_equations]
+  vars --shortcut--> rt[terms]
+  eq --> rt
+  sys --> st[stepper]
+  st --> bc[butcher_table]
+  sys --> log[logger]
+  sys --> tr[tracker]
+```
+
+For easier access there are shortcut methods such as System -> Variables or Variable -> Terms even if the strict relationship lies between adjacent classes.
+
+## Working example: the Lotka-Volterra equations
+
+The Lotka-Volterra equations will be used as the working example for the documentation.
+
+The Lotka-Volterra equations model the change across time in the populations of a prey and a predator species:
+$$
+\frac{dp}{dt}=kp-apd \\
+\frac{dd}{dt}=-rd+bpd
+$$
+$p$ and $d$ are the variables for the prey and predator populations and $k$, $a$, $r$ and $b$ are constant parameters or coefficients.
+
+This differential equation system is nonlinear and cyclical, with prey and predator population oscillating around their own maximum and minimum and with a phase shift between them.
+
+![SCIENCENOTES: Lotka Volterra equation for competition and Predation](https://3.bp.blogspot.com/-N_lMDWKQxoY/WDpB5OP8B0I/AAAAAAAAAFI/t521PcQkwPcMf_jES3FMYsBfiX0qXsPBACLcB/w1200-h630-p-k-no-nu/Volterra_lotka_dynamics.PNG)
+
+## Adding variables
+
+To add dependent variables to the system, use the method `add_variable`:
+
+```Ruby
+lv.add_variable 'predator', 'd', 'Ecosystem predator', 'individuals', type: :organism, rate_equation: '-0.02 * d - 0.00001 * p * d ' 
+```
+
+The arguments for the method and attributes of the variable are:
+
+| Parameter        | Required                                                     | Argument type                                                | Description                                                  |
+| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| `name`           | Yes                                                          | String, with ruby method requirements (no spaces, no special characters) | Name of the variable. A instance variable and accessor methods will be created with it. |
+| `symbol`         | Optional, but highly recommended                             | String, without spaces and without math symbols              | The symbol that will be used in string formulas.             |
+| `title`          | Optional                                                     | String                                                       | A longer title to describe the variable without name restrictions |
+| `unit`           | Optional                                                     | String                                                       | The units of the variable                                    |
+| `type:`          | Optional                                                     | Symbol                                                       | A custom type to group variables.                            |
+| `rate_equation:` | Optional (but must be provided prior integration)            | String                                                       | A string which represent the mathematical expression for the derivative of the variable. |
+| `atol:`          | Optional (for adaptive methods, it is necessary to provide at least one of `rtol` or `atol`) | Float                                                        | Absolute error to be used for the adaptive method            |
+| `rtol:`          | Optional (for adaptive methods, it is necessary to provide at least one of `rtol` or `atol`) | Float                                                        | Relative error to be used for the adaptive method            |
+| `accessor: true` | Optional                                                     | Boolean                                                      | If `true`, creates an instance variable and accessor method with the name provided |
+
+`Bibun` uses a name to identify a variable in the `variables` hash during program execution and a shorter symbol to identify it in the string formulas. It uses the `name` provided to create an accessor method and a instance variable automatically for easier acess to the variable. You can skip this behaviour if you want by passing `accessor: false`. You can always access the variable through the `variables` hash accessor method.
+
+```ruby
+lv.add_variable 'predator', 'd',
+puts lv.predator.symbol # => 'd'
+# Omit accesor creation
+lv.add_variable 'prey', 'p', create_accessor: false
+puts lv.prey.symbol # => NoMethodError
+puts lv.variables['prey'].symbol # => p
+```
+
+For quick math work, you can pass a single ordered argument which will be used as both the name and the symbol. To avoid name collisions with short name methods, the accessor won't be created if you only pass a single ordered argument:
+
+```Ruby
+des.add_variable 'y', rate_function: '3 * y**2 + t'
+puts des.x.name # => NoMethodError
+```
+
+If you do not need the longer names and other attributes, you can use the shortcut method `add_variables` to add them all in a single call:
+
+```ruby
+lv.add_variables({ 'p' => '0.08 * p - 0.001 * p * d',
+                   'd' => '-0.02 * d + 0.00002 * p * d'})
+```
+
+When created, a `DifferentialEquationSystem` object automatically creates a `time` variable with symbol `t` which is used as the independent variable. This can be changed if desired by using the `edit_independent_variable_method`which takes the same arguments of `add_variable` save for those which only apply to dependent variables (`rate_function:`, `atol:`, `rtol:`)
+
+```ruby
+des = Bibun::DifferentialEquationSystem.new
+des.edit_independent_variable('x')
+des.x.value = 10
+puts des.x.value # => 10
+```
+
+## Adding parameters
+
+Although they can be ommited in the simplest cases, most of the time it is desirable to assign values to parameters (quantities that stay the same through the integration) at runtime rather than hard coding them in the formula strings.
+
+Parameters can be added using the `add_parameter` method, The first four ordered arguments are the same as those of variables; the additional keyword argument `value:` can be used to assign it at the same time the parameter is created. As with variables, an instance variable and accessor method are created unless you either pass `accessor: false` or provide a single ordered argument. You can always get the parameters through the hash accessor method `parameters`
+
+The working example implemented using parameters would look like this:
+
+```Ruby
+lv = DifferentialEquationSystem.new
+lv.add_variable 'predator', 'd', 'Ecosystem predator', rate_function: '-r * d + b * p * d'
+lv.add_variable 'prey', 'p', 'Ecosystem prey', rate_function: 'k * p - a * p * d'
+lv.add_parameter 'prey_growth', 'k', 'Prey growth coefficient', value: 0.08
+lv.add_parameter 'prey_consumption', 'a', 'Prey consumption coefficient', value: 0.001
+lv.add_parameter 'predator_decay', 'r', 'Predator decay coefficient', value: 0.02
+lv.add_parameter 'predator_proliferation', 'b', 'Predator proliferation coefficient', value: 0.00002
+```
+
+If you do not need the longer names and other attributes, you can use the shortcut method `add_parameters` to add them all in a single line:
+
+```ruby
+lv.add_parameters({ 'k' => 0.02, 'a' => 0.001, 'r' => 0.02, 'b' => 0.00001 })
+```
+
+## Adding equations
+
+An instance of the `SubDifferentialEquation` class is automatically created along its variable and can be accessed through the `DifferentialSystemVariable#rate_equation` accessor.
+
+```Ruby
+lv.add_variable 'prey', 'p', rate_function: '-r * d + b * p * d'
+puts lv.prey.rate_equation.rate_function # => '-r * d + b * p * d'
+```
+
+Usually this object needs not to be accessed since the mathematical expression of the derivative can be provided using the `rate_function` parameter of the `add_variable` method but is always available if needed:
+
+```ruby
+lv.add_variable 'predator', 'd', rate_equation: '0.02 * d - 0.00001 * p * d ' 
+# Oops, wrong signs, so reedit:
+lv.predator.rate_equation.rate_function = '-0.02 * d + 0.00001 * p * d'
+```
+
+The expression of the rate function must be provided with the form $dx_i/dt = f(X)$ and using the symbols previously assigned to the variables and parameters.
+
+## Adding rate additive terms
+
+There are many situations where a differential equation comprises the sum of several different contributions: for example, in a heat transfer problem one might wish to describe the change in temperature as the sum of one heating contribution and a cooling one, or in a reactor one may wish to distinguish between the rate of generation of a substance and its rate of consumption.
+
+Although the most straightforward manner to implement this would be to assign distinct variable to each of these rate additive terms and them having them summed at each step after performing the integration, with `Bibun` you can provide the differential equation that governs a variable's derivative as the sum of separate additive terms rather than one single formula. Use the `DifferentialEquationVariable#add_rate_term` method to add each term with a name for it and its mathematical expression. This method technically resides in the `SubDifferentialEquation` class but the shortcut is equivalent.
+
+Using terms, our Lotka-Volterra case would look like this:
+
+```Ruby
+lv = DifferentialEquationSystem.new
+lv.add_variable 'predator', 'd', 'Ecosystem predator'
+lv.add_variable 'prey', 'p', 'Ecosystem prey'
+lv.add_parameter 'prey_growth', 'k', 'Prey growth coefficient'
+lv.add_parameter 'prey_consumption', 'a', 'Prey consumption coefficient'
+lv.add_parameter 'predator_decay', 'r', 'Predator decay coefficient'
+lv.add_parameter 'predator_proliferation', 'b', 'Predator proliferation coefficient'
+lv.predator.rate_equation.add_rate_term('decay', '-r * d')
+lv.predator.rate_equation.add_rate_term('predation', 'b * p * d')
+lv.prey.rate_equation.add_rate_term('growth', 'k * p')
+lv.prey.rate_equation.add_rate_term('predation', '-a *p * d')
+```
+
+The `add_rate_term` method takes a `name` and a `rate_equation` argument.
+
+## Assigning values to variables and parameters
+
+Variables need to be given starting values before the integration can be run. The method `DifferentialEquationSystem#assign_values` can be used to pass a hash with both variable and parameter values:
+
+```Ruby
+lv.assign_values({ 'prey_growth' => 0.08, 'prey_consumption' => 0.001, 'predator_decay' => 0.02, 'predator_proliferation' => 0.00002, 'predator' => 100, 'prey' => 1000 })
+```
+
+You can also assign values by directly accessing the `value` instance variable.
+
+```Ruby
+lv.predator.value = 100
+lv.prey_growth.value = 0.08
+lv.prey_consumption.value = 0.001
+# ...
+```
+
+As shown later, in the main method `integrate` you can also pass the values as a hash for the `starting_values` parameter:
+
+```Ruby
+lv.integrate starting_values: { 'prey_growth' => 0.08, 'prey_consumption' => 0.001, 'predator_decay' => 0.02, 'predator_proliferation' => 0.00002, 'predator' => 100, 'prey' => 1000 } # ...
+```
+
+# Performing the integration
+
+## Constant step, non adaptive
+
+The method `integrate` is the main method to perform the integration, that is, starts a run where the variable values at each step are calculated numerically using a numerical method. The `starting_values:` parameter allows a last chance to introduce initial values; `step_size:` is used to input the desired step size ($h$) and the `duration:` parameter determines the lenght of the run.  For a non adaptive method, the total number of steps performed will be total_steps =  duration / step_size since the step size is held constant.
+
+```Ruby
+lv.integrate starting_values: { 'time' => 0, 'prey' => 1000, 'predator' => 50 }, step_size: 1, duration: 100
+puts lv.prey.value # Value at t = 100
+puts lv.predator.value # Value at t = 100
+```
+
+*Note: while it might be tempting to pass the step size argument as a rational value (for example: 1 / 60 for time in minutes when the unit is in hours), rational number operations can slow down the execution by two orders of magnitude. It is recommended to pass the arguement as a float.*
+
+The independent variable (time or the custom name provided) gets assigned a default value of 0 if it was not assigned before. The DES instance will raise an error if any other variable or parameter has a nil value at the moment of integration.
+
+Long integrations with a lot of variables and parameters can take a significant amount of time to complete. A progress bar made with `Formatador` will be displayed in the CLI output. You can supress it if you wish by passing the keyword argument `display_progress: false`.
+
+### Method parameters
+
+| Parameter                | Attribute location                                           | Argument type                                          | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------ |
+| `starting_values:`       | Variable and parameter values before integrating can be set separately or with the `assign_values` method. | `Hash{String => Numeric}`                              | Last chance to pass the values of variables and parameters if they haven't been set. |
+| `step_size:`             | `tracker.step_size`                                          | `Numeric`                                              | Assigns the stepsize to be taken.                            |
+| `duration:`              | `tracker.duration`                                           | `Numeric`                                              | Sets the timespan or limit value until which the integration will be run. |
+| `method:`                | Passed at method call (optional)                             | Can be `:rk4`, `:midpoint` and `:dopr45` at the moment | Specifically sets the integration method. If absent, defaults to `:rk4` for non adaptive and `:dopr45` for adaptive. |
+| `adaptive:false`         | Passed at method call.                                       | `Boolean`                                              | Sets whether to use an adaptive step size or not.            |
+| `display_progress: true` | Passed at method call.                                       | `Boolean`                                              | Specifies whether to print a progress bar to `stdout` or not. |
+
+
+
+## Logging integrations and storing in a file
+
+Tracking the evolution of the variables and other quantities across the integration is likely the most important use of a numerical integrator. Depending on the case, only some variables might be important to store to simplify the storage file or, alternatively, it might be that there are different quantities or expressions besides the variables which one might want to track and store for further analysis and inspection.
+
+`Bibun` keeps a log that is independent of the variables to easily customize and manipulate it at will. The `logger` object from the DES instance lets you define what you desire to track and record. The logger must be set up before staring the integration. Several different quantities can be set to be recorded with it:
+
+- Variables of the DES
+- Additive terms for the variables of the DES
+- Custom mathematical expressions which are functions of the variables and parameters of the DES.
+- The iteration counter, which is akin to the `ROW_NUMBER` function for SQL queries.
+
+For the purposes of writing to a `.csv` file, columns are written in the order with which they were added to the logger.
+
+## Recording a variable
+
+To record variables, use the method `add_variables_to_log` . Provide a hash with the variable names and the decimal places to which the values are going to be rounded.
+
+```Ruby
+lv.logger.add_variables({ 'time' => 0 , 'predator' => 1, 'prey' => 1 })
+```
+
+If multiple variables share the same decimals, you can use the following shortcut method:
+
+```ruby
+# After the decimals comes a variable length parameter list
+lv.logger.add_same_decimals_to_variables(2, 'time', 'predator', 'prey')
+```
+
+
+
+## Recording a rate additive term
+
+If the differential equations of the variables where introduced as separate additive terms, they can be recorded individually. To record the contribution of a term to the change of the variable in one step, use the method `DifferentialEquationLogger # add_rate_term`, providing the name of the variable, the name of the rate additive term, and the number of decimals places to round the value.
+
+```Ruby
+lv.logger.add_rate_term('prey', 'growth', 2)
+```
+
+A variable along its additive terms can be added to the log in a single line with the method `logger#add_variable_with_terms`, passing a single common value for the decimal places:
+
+```ruby
+lv.logger.add_variable_with_terms('prey', 2)
+# Equivalent to:
+#   lv.logger.add_variables({'prey' => 2})
+#   lv.logger.add_rate_term('prey', 'growth', 2)
+#   lv.logger.add_rate_term('prey', 'predation', 2)
+```
+
+As it will be shown later, in the log the rate additive term are such that the value of the variable at the next row equals the sum of its value in the current row plus all the rate additive terms.
+
+## Recording the step number
+
+When the step size is not 1, it may be desirable to add a row counter column. `logger.add_step_state` adds this step counter without needing any argument.
+
+## Recording a expression
+
+Custom calculations that are a function of the DES variables and parameters can be set to be tracked during the integration. To record a custom mathematical expression, use the method `DifferentialEquationLogger # add_expression`, providing the name of the expression, the mathematical formula of the expression, and the number of decimals places to round the value.
+
+Make sure the expression name is not the same to any variable name.
+
+```Ruby
+lv.logger.add_expression('prey_predator_ratio', 'p / d', 2)
+```
+
+## Adding all to the logger
+
+For quick cases, `add_all` lets adding all variables to the logger in a single line passing a common value for the decimal places. Using `with_terms: true` includes all rate terms if they were specified.
+
+```ruby
+# 3 decimal places for all variables and including all terms
+lv.logger.add_all(3, with_terms: true)
+```
+
+This method is available as a shortcut from the DES object as `log_all`
+
+```Ruby
+# 3 decimal places for all variables and including all terms
+lv.log_all(3, with_terms: false)
+```
+
+## Changing the interval of logging
+
+Using small step sizes could result in huge log files and slow performance as logs grow in the memory. One can preserve the precision of smaller step sizes and keep the log light by using a different interval for logging. For example, if time is in seconds and the step size is 1 s but we wish to log results only every 30 seconds, we can adjust it with the `logger#logging_interval` writer method:
+
+```ruby
+lv.logger.logging_interval = 30
+```
+
+## Exporting the log to a `.csv` file
+
+After performing the integration, the method `logger#save_to_file` exports the log of the integration to the provided file path. Column order is that of the order with which the quantities to log were input.
+
+```Ruby
+lv.logger.save_to_file('Predation.csv')
+```
+The whole program using all the features would be this:
+
+```Ruby
+lv = DifferentialEquationSystem.new
+lv.add_variable 'predator', 'd', 'Ecosystem Predator'
+lv.add_variable 'prey', 'p', 'Ecosystem Prey'
+lv.add_parameter 'prey_growth', 'k', 'Prey growth coefficient'
+lv.add_parameter 'prey_consumption', 'a', 'Prey consumption coefficient'
+lv.add_parameter 'predator_decay', 'r', 'Predator decay coefficient'
+lv.add_parameter 'predator_proliferation', 'b', 'Predator proliferation coefficient'
+lv.prey.rate_equation.add_rate_term('decay', '-r * d')
+lv.prey.rate_equation.add_rate_term('predation', 'b * p * d')
+lv.predator.rate_equation.add_rate_term('growth', 'k * p')
+lv.predator.rate_equation.add_rate_term('predation', '-a *p * d')
+
+lv.add_variables_to_log({ 'time' => 0 })
+lv.add_variables_to_log({ 'predator' => 1 })
+lv.logger.add_rate_term('predator', 'decay', 2)
+lv.logger.add_rate_term('predator', 'predation', 2)
+lv.add_variables_to_log({ 'prey' => 1 })
+lv.logger.add_rate_term('prey', 'growth', 2)
+lv.logger.add_rate_term('prey', 'predation', 2)
+lv.logger.add_expression('prey-predator_ratio', 'p / d', 2)
+
+lv.assign_values({ 'prey_growth' => 0.08, 'prey_consumption' => 0.001, 'predator_decay' => 0.02, 'predator_proliferation' => 0.00002 })
+lv.integrate starting_values: { 'time' => 0, 'prey' => 1000, 'predator' => 50 }, step_size: 1, duration: 100
+lv.logger.save_to_file('Predation.csv')
+```
+Checking some rows of the generated file:
+
+| time | predator | predator - decay | predator - predation |  prey  | prey - growth | prey - predation | prey-predator ratio |
+| :--: | :------: | :--------------: | :------------------: | :----: | :-----------: | :--------------: | :-----------------: |
+|  37  |   80.8   |      -1.63       |         3.5          | 2141.2 |    171.17     |     -174.87      |        26.5         |
+|  38  |   82.7   |      -1.67       |         3.57         | 2137.5 |    170.72     |     -178.41      |        25.86        |
+|  39  |   84.6   |      -1.71       |         3.63         | 2129.8 |    169.94     |     -181.66      |        25.19        |
+
+The sums of the terms for each variable equal the value of the variable for the next step. Here at time 37 we can verify that the value for time 38 for the predator population is $80.8 - 1.63 + 3.5  = 82.67$, showing the separate contributions due to predation and decay.
+
+*NOTE: when the logging interval is not equal to the step size, the term logs account for it in order to always represent the total change between two logging rows, so their logged values will differ if the logging interval change.*
+
+## Accessing the logs programatically
+
+After integrating, you can access the logs through the shortcut `DifferentialEquationSystem#logs[]` or with `logger.logs` using the proper key, which is:
+
+- For variables, their `name`
+- For additive rate terms, the variable `name` followed by the term `name` with a semicolon in between. For example: `lv.logs['predator:decay']`
+- For custom expressions, the name provided while creating the entry.
+- For the step, use `des.logs['step']`
+
+You can also access the logs of variables and rate additive terms through them. The log will be returned as an array with the value gotten at each logging step. so you can use standard array methods on them.
+
+```ruby
+# Get last ten step values
+last_prey_values = lv.logs['prey'].last(10)
+# From the logger
+last_prey_values = lv.logger.logs['prey'].last(10)
+```
+
+# Using an adaptive method
+
+Passing `adaptive: true` to the `integrate` method uses the fifth order (with 4-order for error evaluation) Dormand Prince method. Several extra arguments must be passed overall. You need to pass error tolerances to at least one dependent variable and you can do it while adding them or later by the accessor methods:
+
+```Ruby
+lv.add_variable 'prey', 'p', rate_function: 'k * p - a * p * d', atol: 0.1, rtol: 0.01
+# Alternatively
+lv.prey.atol = 0.1
+lv.prey.rtol = 0.01
+```
+
+You can pass only relative or absolute tolerance or both (the stepper will take the sum of both for error evaluation, see formulas below). Variables are inherently created with a value of zero for both tolerances. Failure to assign nonzero tolerances in at least one dependent variable will raise an error when calling the `integrate` method.  You can pass tolerances for all variables at once with the `set_global_tolerances` method if you wish, although this is only advisable if they share the same units and order of magnitude:
+
+```ruby
+lv.set_global_tolerance 0.1, 0.01 # atol of 0.1 and rtol of 0.01
+```
+
+The stepper evaluates the error at each iteration and increases the initial step size given if it the overall error is smaller than the aggregate `err` index or decreases the error and repeats the iteration if the error surpasses the aggregate. Because criteria for calculating the error and changing the step size is not set in stone, `Bibun` uses the following formulas[^1] :
+$$
+err = \sqrt{\frac{1}{N}\sum{(\frac{\Delta}{scale})^2}} \\
+\Delta = x_{5^{th}order}-x_{4^{th}order} \\
+scale = atol+rtol\times max(x_n,x_{n+1})
+$$
+Where N is the number of variables with nonzero tolerance. Step size is decreased and the step performed again if err < 1 and step size is increased otherwise. The size adjustment is done according to:
+$$
+h_{next}=h \times clamp(0.9(\frac{1}{err})^{1/5},1/5, 10)
+$$
+The 0.9 safety factor is a reccomendation by J.C. Butcher[^2] while the 1/5..10 range is a recommendation by W. H. Press.
+
+### Using dense output
+
+Because an adaptive method is constantly adjusting its step size, the log it produces is unevenly spaced, which might be undesirable in certain circumstances, such as creating a uniform graph or closely monitoring its behaviour. You can adjust the logging interval as you would in the non-adaptive case; if you do, the stepper generates the rows at each interval using a polynomial interpolation of fourth degree. This is known as a dense output.
+
+```ruby
+lv.logger.logging_interval = 0.02
+lv.integrate adaptive: true # Uses dense output
+```
+
+# Custom control by single step
+
+Software packages offer an ability to create events in their own syntax in order to control the integration process, one common example being the ability to interrupt and finish the integration if the values of the variables surpass certain limits.
+
+`Bibun` offers the `single_step` method to perform one single step of the integration process. This method take the same arguments than the integrate method, but will only peform the setup of the integration run the first time is called (the `starting_values:` parameter is only taken into account the first time, then ignored for any further calls to `single_step` since variables now depend on the integration proces).
+
+Because the `integrate` method simply adds a loop to the basic stepping routine, you can easily set an integration with the `single_step` method and a loop and use Ruby to create any condition or perform any action you want in the middle of the integration. 
+
+Below are shown several examples of what you can do by using a custom loop along `single step`:
+
+```ruby
+# Use a constant step method. Integrate over a day (time is in minutes).Stop integration if a variable crosses a threshold. Preemptive setup is shown.
+reactor.assign_values({'time' => 0, 'chemical_oxygen_demand' => 100, 'oxygen' => 5.0 })
+reactor.step_size = (1/60r).to_f # One minute
+1440.times do # 1 day run
+  reactor.single_step # reactor is the DES
+  break if reactor.chemical_oxigen_demand < 5
+end
+# For a circuit known to stabilize asynthotically, stop when the maximum difference across the last 10 iterations falls below a threshold.
+while unstable
+  circuit.single_step # Circuit is the DES
+  last_values = circuit.logs['voltage'].last(10)
+  unstable = (last_values.max - last_values.min).abs > 0.1
+end
+# Using an adaptive process, stop if a variables stays below a 50 000 UFC / mL threshold for 10 min.
+1000.times do
+  medium.single_step adaptive: true
+  ar = medium.logs['time']  
+  lower_bound = ar.find_index(ar.select {|s| s > ar.last - 10 }.min)  
+  break if medium.logs['staphylococcus'][lower_bound..-1].none? { |s| s >= 5E4 }
+end
+# Harvest a population extracting certain quantity whenever it grows about a threshold and add feed if it falls below a threshold.
+(365 * 24).times do
+  tank.single_step
+  tank.shrimp.value -= 5_000 if tank.shrimp.value > 25_000
+  tank.daphnia.value += 30_000 if tank.daphnia.value < 40_000  
+end    
+```
+
+# Serialization
+
+It might be convenient to save the conditions to perform a integration run when performing many of them. The main class has `to_json` and `from_json` methods to write and read from JSON objects. The look of the previous example as a JSON is the following:
+
+```json
+{
+  "variables": [
+    {
+      "name": "predator",
+      "symbol": "d",
+      "title": "Ecosystem predator",
+      "unit": null,
+      "terms": [
+        {
+          "name": "decay",
+          "rate_function": "-r * d"
+        },
+        {
+          "name": "predation",
+          "rate_function": "b * p * d"
+        }
+      ]
+    },
+    {
+      "name": "prey",
+      "symbol": "p",
+      "title": "Ecosystem prey",
+      "unit": null,
+      "terms": [
+        {
+          "name": "growth",
+          "rate_function": "k * p"
+        },
+        {
+          "name": "predation",
+          "rate_function": "-a *p * d"
+        }
+      ]
+    }
+  ],
+  "parameters": [
+    {
+      "name": "prey_growth",
+      "symbol": "k",
+      "title": "Prey growth rate",
+      "unit": null,
+      "value": 0.08
+    },
+    {
+      "name": "prey_consumption",
+      "symbol": "a",
+      "title": "Prey predation coefficient",
+      "unit": null,
+      "value": 0.001
+    },
+    {
+      "name": "predator_decay",
+      "symbol": "r",
+      "title": "Predator decay rate",
+      "unit": null,
+      "value": 0.02
+    },
+    {
+      "name": "predator_proliferation",
+      "symbol": "b",
+      "title": "Predator proliferation coefficient",
+      "unit": null,
+      "value": 0.00002
+    }
+  ],
+  "logging": [
+    {
+      "type": "variable",
+      "variable": "time",
+      "decimals": 0
+    },
+    {
+      "type": "variable",
+      "variable": "predator",
+      "decimals": 2
+    },
+    {
+      "type": "term",
+      "term": "decay",
+      "variable": "predator",
+      "decimals": 2
+    },
+    {
+      "type": "term",
+      "term": "predation",
+      "variable": "predator",
+      "decimals": 2
+    },
+    {
+      "type": "variable",
+      "variable": "prey",
+      "decimals": 2
+    },
+    {
+      "type": "term",
+      "term": "growth",
+      "variable": "prey",
+      "decimals": 2
+    },
+    {
+      "type": "term",
+      "term": "predation",
+      "variable": "prey",
+      "decimals": 2
+    },
+    {
+      "type": "expression",
+      "name": "prey-predator ratio",
+      "formula": "p / d",
+      "decimals": 2
+    }
+  ],
+  "values": {
+    "time": 0,
+    "predator": 50,
+    "prey": 1000
+  },
+  "simulation_options": {
+    "step_size": 1,
+    "duration": 100,
+    "logging_interval": 5
+  }
+}
+```
+
+Although variables and parameters are more general and seldom worth skipping, the `logging`, `values` and `integration_options` might be skipped and assigned in the program. Loading is trivial:
+
+```Ruby
+lv.from_json(File.read('tmp/lotka_volterra.json'))
+lv.integrate
+```
+
+There are also `to_toml` and `from_toml` versions to work with TOML files, which I find more confortable to manually create and edit:
+
+```toml
+[[variables]]
+name = "predator"
+symbol = "d"
+title = "Ecosystem predator"
+unit = ""
+
+[[variables.terms]]
+name = "decay"
+rate_function = "-r * d"
+
+[[variables.terms]]
+name = "predation"
+rate_function = "b * p * d"
+
+[[variables]]
+name = "prey"
+symbol = "p"
+title = "Ecosystem prey"
+unit = ""
+
+[[variables.terms]]
+name = "growth"
+rate_function = "k * p"
+
+[[variables.terms]]
+name = "predation"
+rate_function = "-a *p * d"
+
+[[parameters]]
+name = "prey_growth"
+symbol = "k"
+title = "Prey growth rate"
+unit = ""
+value = 0.08
+
+[[parameters]]
+name = "prey_consumption"
+symbol = "a"
+title = "Prey consumption coefficient"
+unit = ""
+value = 0.001
+
+[[parameters]]
+name = "predator_decay"
+symbol = "r"
+title = "Predator decay rate"
+unit = ""
+value = 0.02
+
+[[parameters]]
+name = "predator_proliferation"
+symbol = "b"
+title = "Predator proliferation coefficient"
+unit = ""
+value = 2.0e-05
+
+[[logging]]
+type = "variable"
+variable = "time"
+decimals = 0
+
+[[logging]]
+type = "variable"
+variable = "predator"
+decimals = 2
+
+[[logging]]
+type = "term"
+term = "decay"
+variable = "predator"
+decimals = 2
+
+[[logging]]
+type = "term"
+term = "predation"
+variable = "predator"
+decimals = 2
+
+[[logging]]
+type = "variable"
+variable = "prey"
+decimals = 2
+
+[[logging]]
+type = "term"
+term = "growth"
+variable = "prey"
+decimals = 2
+
+[[logging]]
+type = "term"
+term = "predation"
+variable = "prey"
+decimals = 2
+
+[[logging]]
+name = "prey-predator ratio"
+type = "expression"
+formula = "p / d"
+decimals = 2
+
+[values]
+time = 0
+predator = 50
+prey = 1000
+
+[simulation_options]
+step_size = 1
+duration = 100
+logging_interval = 5
+```
+
+*NOTE: TOML has no specification for null values andso far the only way is to omit the key-value pair if the value is null. I have not found a library which correctly implements this behaviour. This can cause inconsistencies when exporting to TOML and use immediately for loading. Check for "" assignments in the generated TOML file.*
+
+# Subclassing: the general integration method
+
+Although the default class might give good functionality, some might desire to inherit from `Bibun::DifferentialEquationSystem` to implement some custom procedures within the calculation of each step. For example, physical systems might want to prevent variables to reach negative values, which can happen at near zero regions with not small enough step sizes. The main loop is conveniently separated into different subroutines which are ideal to override in the subclasses:
+
+```ruby
+while syms.ind_var.value < step_tracker.ending_point
+  unitary_step
+  @progress_bar.increment if display_progress
+end
+
+def unitary_step
+  # Calculation of the variable changes for the next step  
+  walk_step
+  # Logging the values using those the prior variables values and their changes 
+  append_log
+  # Finally commiting the changes into the variables
+  change_variables
+end
+```
+
+Lets say we simply want to set variable values to zero if they happen to become negative. We can override `change_variables` in the subclass to set those which became negative to zero for the next iteration.
+
+```ruby
+# Subclass
+def change_variables
+  super
+  variables.each_value do |v| 
+      v.value = 0 if v.value.negative?
+  end    
+end  
+```
+
+# Validation
+
+The methods have been validated mostly against differential equations with known analytical solutions and in some cases against tabulated data from book examples or simple steps against Libre Calc software. Specific calculations and criteria for modifying the step size are not set into stone and for the popular `ode45` method the documentation does not disclose it, so I cannot guarantee an exact correspondence with it.
+
+So far the numerical methods here are explicit and do not take specific features of the DES into consideration so limitations such as unsuitability for stiff equations or gradual shift of cyclic behaviour over time apply.
+
+## Bugs, errors and limitations
+
+Although testing has been made to ensure the library performs the integration correctly, it is unavoidable to get errors of mathematical nature with certains inputs (for example, division by zero). The library does not check or takes preemptive action against errors of this nature. Some of the errors of this nature are:
+
+- Given the exponential nature of many differential equations, it is frequently the case that variables grow quickly to very high values eventually surpassing the `Float` type maximum. A single wrong sign in the rate functions can trigger this, so check those accordingly if the growth behaviour is unexpected or use a custom loop with a stop condition.
+- Similarly, division by a variable might trigger very large values if such variable approaches zero.
+- Operations with the `Rational` number type are quite slower. Passing a `Rational` number as the step size can cause the integration to take two extra orders of magnitude more time than the float case, so it is recommended to pass floats like `1/60r.to_f`.
+- As of the initial version, I have not tested the changing of the `logging_interval` attribute in the midst of integration because I have not found it likely for it to need manual adjustment. It will trigger inconsistent behaviour for the adaptive method.
+
+# Future changes
+
+As of the initial release, the `Bibun` gem is likely to undergo changes in order to solidify the best functionality for engineering needs. Some aspects like the core stepping process are probably staying largely unmodified although it might change to accomodate the plans to include the Dormand-Prince 8(5,3) method. The serialization feature is the one most likely to evolve. Changes to the outer methods of the interface that could break the API will be implemented if there's common enough use cases for it until reaching a 1.0 version.
+
+[^1]: Numerical Recipes. The Art of Scientific Computing. Third Edition, by W. H. Press
+[^2]:  Numerical Methods for Ordinary Differential Equations. Second Edition, by J.C. Butcher.