bibun 0.0.0

data/lib/bibun/differential_stepper.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require_relative 'differential_butcher_table'
+
+module Bibun
+  class DifferentialEquationSystem
+    # This class handles the inner process of numerical calculations to perform each integration step and set
+    # the changes to add to the variables to udpate them to the next step.
+    class DifferentialStepper
+      # @return [Bibun::DifferentialButcherTable] The butcher table with the info to perform the Runge-Kutta
+      #   integration.
+      attr_accessor :butcher_table
+      # @return [Bibun::DifferentialEquationSystem] Reference to the outer DES object.
+      attr_accessor :system
+      # @return [Bibun::DifferentialEquationSystem::SymbolGroup] Reference to the SymbolGroup object of the outer DES
+      #   object.
+      attr_accessor :syms
+      # @return [Bibun::DifferentialEquationSystem::StepTracker] Reference to the step tracker of the outer DES object.
+      attr_accessor :tracker
+      # @return [Array<Keisan::Calculator>] Array with the calculators for each formula of the interpolation (this is
+      #   necessary to be able to cache the AST for each formula and improve performance).
+      attr_accessor :dense_calculators
+      # @return [Hash] A nested hash used to pass the values to log to the logger object.
+      attr_accessor :terms_log
+
+      # Basic initialization. +StepTracker+ and +GroupSymbol+ objects are assinged for easier access.
+      def initialize(parent_system, tracker, syms)
+        @system = parent_system
+        @tracker = tracker
+        @syms = syms
+        @butcher_table = DifferentialButcherTable.new
+        @adaptive = false
+      end
+
+      # Preparation prior the taking the first step.
+      def prepare(method: nil)
+        set_buffers
+        butcher_table.load_preset(method:) if butcher_table.empty?
+        return unless butcher_table.adaptive?
+
+        raise 'No tolerances provided for adaptive integration' unless syms.tolerances_provided?
+
+        set_interpolation if dense_output?
+      end
+
+      # Quick way to check if dense output has to be given.
+      # @return [Boolean]
+      def dense_output? = butcher_table.adaptive? && !tracker.logging_interval.nil?
+
+      # Step for explicit Runge-Kutta methods
+      def walk_step(step_size)
+        if butcher_table.adaptive?
+          adaptive_loop(step_size)
+        else
+          straightforward_step(step_size)
+        end
+      end
+
+      # Performs a single step, resulting in new values assigned to +DifferentialSystemVariable.step_size+
+      def straightforward_step(step_size, alternate_weights: false)
+        estimate_k_steps(step_size)
+        combine_with_weighted(step_size, butcher_table.weights)
+        combine_with_weighted(step_size, butcher_table.alternate_weights, alternate: true) if alternate_weights
+      end
+
+      # Loop for adaptive methods, which results in new values of +DifferentialSystemVariable.step_size+ and a
+      # new +StepTracker.step_size+
+      def adaptive_loop(step_size)
+        runner_step_size = step_size
+        acceptable_error = false
+        i = 0
+        until acceptable_error
+          i += 1
+          # First run
+          straightforward_step(runner_step_size, alternate_weights: true)
+          result = evaluate_error
+          runner_step_size *= result[:factor].clamp(1/5r, 10) # Suggestion by W.H. Press
+          if result[:err] <= 1
+            acceptable_error = true
+          else
+            # Perform again with lower step size, do not correct step_size again.
+            # Undo the change done from the previous, wrong step size.
+            syms.undo_term_changes
+            straightforward_step(runner_step_size, alternate_weights: true)
+            if evaluate_error[:err] <= 1
+              acceptable_error = true
+            else
+              # Adjust again step size for next iteration of the loop.
+              syms.undo_term_changes
+              runner_step_size *= result[:factor].clamp(1/5r, 10)
+            end
+          end
+          raise 'Too many adapations' if i >= 5
+        end
+        tracker.next_step_size = runner_step_size
+      end
+
+      # Provides to the logger the variable value that correspond to the current logging point.
+      # The leaps array and index are both provided to be able to assess the relative position of the index.
+      # @return [Numeric] The value to log for the variable.
+      def variable_log_value(variable, leaps, index)
+        if dense_output?
+          dense_interpolation(variable, leaps[index])
+        else
+          variable.value + variable.step_change
+        end
+      end
+
+      # Provides to the logger the rate additive term value that correspond to the current logging point.
+      # The leaps array and index are both provided to be able to assess the relative position of the index.
+      # @return [Numeric] The value to log for the rate additive term.
+      def term_log_value(term, marks, index)
+        if dense_output?
+          term_dense_accumulation(term, marks, index)
+        else
+          term.report_and_reset
+        end
+      end
+
+      # This routine records the amount of change that keeps unregistered at the end of each walking step and adds it
+      # to the first logging step of the next walking step. Also ensures only the change caused by each individual
+      # logging step is provided for those beyond the first.
+      # @return [Numeric] The net amount of change due to the rate additive term for dense interpolation.
+      def term_dense_accumulation(term, marks, index)
+        value = 0
+        interpol = dense_interpolation(term, marks[index])
+        value += interpol
+        if index == 0
+          value += term.lagging_change
+          term.lagging_change = 0
+        else
+          value -= term.last_interpol
+        end
+        term.last_interpol = interpol
+        value
+      end
+
+      private
+
+      # Set the variable arrays for the k values (k_steps)
+      def set_buffers
+        stages = butcher_table.stages
+        syms.rate_variables.each_value do |v|
+          v.k_steps = [*0..stages]
+        end
+        syms.terms_array.each { |s| s.k_steps = [*0..stages] }
+      end
+
+      # Calculates the k values of the Runge-Kutta methods.
+      def estimate_k_steps(step_size)
+        stages = (0..butcher_table.stages)
+        stages.each do |s|
+          calculate_stage(step_size, s, last: s == stages.max)
+        end
+      end
+
+      # Each individual k value calculation. NOTE: here the calculation k = h * F(t + ch, y + Σ(a_is)) instead of
+      # k = F(t + ch, y + Σ(a_is)) to resemble books on computer numerical methdos like Numerical Recipes.
+      # Effect: this updates the +k_steps+ values of +DifferentialSystemVariable+ and +DifferentialTerm+ and the
+      # buffer value for the next stage.
+      def calculate_stage(step_size, stage, last: false)
+        syms.ind_var.buffer_value = syms.ind_var.value + butcher_table.nodes[stage] * step_size
+        syms.rate_variables.each_value do |v|
+          v.k_steps[stage] = step_size * v.rate_equation.derivative_value(syms.syms_buffers_hash, stage)
+          v.terms.each_value { |tv| tv.k_steps[stage] *= step_size }
+        end
+        return if last
+
+        syms.rate_variables.each_value do |v|
+          v.buffer_value = v.value + (0..stage).map { |i|
+            butcher_table.matrix_coefficients[stage][i] * v.k_steps[i]
+          }.sum
+        end
+      end
+
+      # Performs the sum pondered with the Butcher table weights for the ks.
+      # Effect: updates +DifferentialSystemVariable.StepChange+ or +DifferentialSystemVariable.alternate_step_change+,
+      # depending on the +alternate+ parameter.
+      def combine_with_weighted(step_size, weights, alternate: false)
+        writer = alternate ? :alternate_step_change= : :step_change=
+        syms.rate_variables.each_value do |v|
+          v.send writer, v.k_steps[0..(weights.size - 1)].zip(weights)
+                          .reduce(0) { |sum, e| sum + e[0] * e[1] }
+        end
+        # Calculation of separate term contributions is unnecessary for lesser order estimations
+        unless alternate
+          syms.terms_array.each do |t|
+            term_contribution = t.k_steps[0..weights.size].zip(weights).reduce(0) { |sum, e| sum + e[0] * e[1] }
+            t.register_step_change(term_contribution)
+            t.variable.term_changes[t.name] = term_contribution
+          end
+        end
+        syms.ind_var.send writer, step_size
+      end
+
+      # For adaptive methods, evaluates the error from the difference in estimation between the two weight sets
+      # of varying order considering the tolerances provided.
+      # @return [Hash{Symbol => Numeric}] A hash with the err index to judge whether to increase or reduce the step
+      #   size and the factor by which the current step has to be multiplied.
+      def evaluate_error
+        vars = syms.vars_with_tols
+        # err calculation according to W. H. Press
+        relative_sq_sum = vars.values.reduce(0) do |acum, v|
+          acum + (v.delta / v.scale.to_f)**2
+        end
+        err = Math.sqrt(relative_sq_sum / vars.size)
+        # 0.9 is a recommended factor by Butcher
+        factor = 0.9 * (1 / err)**(1 / butcher_table.order.to_f)
+        { err: err, factor: factor }
+      end
+
+      # Part of the preparation which loads calculators for the interpolation functions.
+      def set_interpolation
+        @dense_calculators = []
+        butcher_table.interpolation_formulas.length.times { @dense_calculators.push Keisan::Calculator.new(cache: true) }
+      end
+
+      # Calculates the interpolated value of the variables or terms given the "slot", that is, the ordinal of the log
+      # for the given step.
+      # @param sym [DifferentialSystemVariable] The variable whose value is going to be calculated.
+      # @param point [Numeric] The independent variable value of the row to be recorded within the step.
+      def dense_interpolation(sym, point)
+        return tracker.current_logging_point if sym.instance_of?(DifferentialSystemVariable) && sym.independent?
+
+        data = sym.interpolator_hash.merge(butcher_table.interpolation_constants)
+        dense_calculators[0..-2].each_with_index do |c, j|
+          r_coef = c.evaluate(butcher_table.interpolation_formulas["r#{j + 1}"], data)
+          data.store "r#{j + 1}".to_sym, r_coef
+        end
+        data.store :theta, tracker.theta(point)
+        coef_keys = %i[r1 r2 r3 r4 r5 theta]
+        poly_coefs = data.slice(*coef_keys)
+        dense_calculators.last.evaluate(butcher_table.interpolation_formulas['final'], poly_coefs)
+      end
+    end
+  end
+end

data/lib/bibun/differential_system_parameter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'differential_system_symbol'
+
+module Bibun
+  # Parameters lack buffer values and logs, but can take a reference interval to retrieve at random
+  class DifferentialSystemParameter < Bibun::DifferentialSystemSymbol
+    attr_accessor :reference_data
+
+    # In progress. A ReferenceData class is in mind to be able to pass reference ranges.
+    def sample
+      @value = @reference_data.random_value
+    end
+
+    # json serializer
+    def to_json(*_args)
+      { 'name' => name, 'symbol' => symbol, 'title' => title, 'unit' => unit, 'value' => value }.to_json
+    end
+    
+  end
+end

data/lib/bibun/differential_system_symbol.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bibun
+  # This class is not used directly, but implements behaviour common to DifferentialSystemVariable and
+  # DifferentialSystemParameter. Here 'symbol' refers to either a parameter or a variable.
+  class DifferentialSystemSymbol
+    # @return [String] The name of the symbol which is referenced in hashes and accessor methods.
+    attr_accessor :name
+    # @return [String] The string, usually short, which is used in string formulas for _Keisan::Calculator_
+    attr_accessor :symbol
+    # @return [String] A string to designate the variable for printing, so it can have spaces, dashes, etc.
+    attr_accessor :title
+    # @return [String] A short string to document the units of the symbol
+    attr_accessor :unit
+    # @return [Numeric] The numeric value which the symbol holds at one given moment.
+    attr_accessor :value
+
+    # Regular initialization.
+    def initialize(name:, symbol:, title: nil, value: nil, unit: nil)
+      @name = name
+      @symbol = symbol
+      @title = title
+      @value = value
+      @unit = unit
+    end
+
+    # Method to express the current value of the symbol with units (e.g. "30 m")
+    # @param significant_figures[Integer] The decimal places to round the value of the symbol.
+    # @return [String] The value with units.
+    def with_units(significant_figures = nil)
+      quantity = significant_figures.nil? ? value : value.round(significant_figures).to_s
+      "#{quantity} #{@unit}"
+    end
+  end
+end

data/lib/bibun/differential_system_variable.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Bibun
+  # Class to implement variables (in this library, variables change their value as the independent variable change,
+  # parameters keep their value fixed across the simulation)
+  class DifferentialSystemVariable < Bibun::DifferentialSystemSymbol
+
+    # Reference to the +SubDifferentialEquation+ object that contains the function for its derivative.
+    attr_accessor :rate_equation
+    # Adds a custom type which can be useful for grouping variables and subclassing.
+    attr_accessor :type
+    # Reference to the quantity change that is caused by a integration step and which is eventually added to the value.
+    attr_accessor :step_change
+    # For adaptive embedded methods, it stores the quantity change calculated with the alternative set of weights of
+    # a different order in order to calculate the error of the intergration step.
+    attr_accessor :alternate_step_change
+    # This is hash with the quantity changes caused by each of the rate additive terms, when those are defined.
+    # Their sum equals the step change.
+    attr_accessor :term_changes
+    # Absolute tolerance to consider for adpative methods.
+    attr_accessor :atol
+    # Relative tolerance to consider for adaptive methods.
+    attr_accessor :rtol
+    # Array which holds the k quantities (k1, k2, k3, etc in Runge Kutta methods) corresponding to each stage of the
+    # Runge Kutta method. Since arrays start in zero, add 1 to be equal to the book formulas.
+    attr_accessor :k_steps
+    # Value for the variable to be taken for the evaluation of the next k and which is calcualted using the matrix
+    # coefficients a11, a21, a22, a31, a32, a33... of the Butcher Table and which does not require further storing.
+    # Also used as temporary cache for expression calculations when logging.
+    attr_accessor :buffer_value
+    # Boolean to distinguish the independent variable from the dependent variables.
+    attr_reader :independent
+    alias independent? independent
+
+    # Regular initialization.
+    def initialize(name:, symbol:, title: nil, value: nil, unit: nil, type: nil, rate_function: nil,
+                   atol: nil, rtol: nil, independent: false)
+      super(name: name, symbol: symbol, title: title, value: value, unit: unit)
+      @type = type
+      @term_changes = {}
+      @rate_equation = SubDifferentialEquation.new(self) unless type == :independent_variable
+      @atol = atol || 0
+      @rtol = rtol || 0
+      @independent = independent
+      rate_equation.rate_function = rate_function unless rate_function.nil?
+    end
+
+    # Shortcut attribute writer for the rate function of the _SubDifferentialEquation_ object
+    # @param [String] formula The mathematical expression of the formula in native Ruby.
+    # @example
+    #   variables['temperature'].rate_function = '3 * t^(1.5)'
+    def rate_function=(formula)
+      rate_equation.rate_function = formula if rate_equation.terms.empty?
+    end
+
+    # Shortcut method to adds a rate term to the _SubDifferentialEquation_ object.
+    # see {SubDifferentialEquation#add_rate_term}
+    def add_rate_term(name, formula)
+      rate_equation.add_rate_term name, formula
+    end
+
+    # Routine to convert to json.
+    def to_json(*_args)
+      basic_hash = { 'name' => name, 'symbol' => symbol, 'title' => title, 'unit' => unit }
+      rates_hash = if rate_equation.terms.empty?
+                     { 'rate_function' => rate_equation.rate_function }
+                   else
+                     { 'terms' => rate_equation.terms.values }
+                   end
+      basic_hash.merge(rates_hash).to_json
+    end
+
+    # Formula to evaluate error for adaptive methods. From Numerical Recipes by W. H. Press.
+    # Notice how both tolerances influence the result so that is always higher than either one of them.
+    # @return [Float] the combined value of the scale.
+    def scale = atol + rtol * [value + step_change, value + alternate_step_change].max
+
+    # Difference between the estimations of embedded methods (the actual value cancels out).
+    # @return [Float] the difference between both estimations.
+    def delta = step_change - alternate_step_change
+
+    # Quick method to check if the variable has additive rate terms defined.
+    # @return [Boolean]
+    def terms? = !rate_equation.terms.empty?
+
+    # Returns the hash of rate additive terms. Shortcut to access from the variable itself.
+    # @return [Hash{String => DifferentialTerm}] The hash with the additive terms for the variable.
+    def terms = rate_equation.terms
+
+    # Hash with the values necessary for polynomial interpolation for dense outputs. This is fed as the second
+    # argument for Keisan::Calculator#evaluate.
+    # @return [Hash{Symbol => Float}] the hash with the key value pairs.
+    def interpolator_hash
+      vals = { y0: value, y1: value + step_change }
+      k_hash = k_steps.map.with_index { |k, i| ["k#{i + 1}".to_sym, k] }.to_h
+      vals.merge(k_hash)
+    end
+
+    # Class that handle the differential equation which governs the variable's rate of change. Shortcut methods on the
+    # variable make its access non essential, but are provided anyway.
+    class SubDifferentialEquation
+      attr_accessor :name, :rate_function, :terms, :current_value, :rate_variable
+
+      def initialize(parent_variable, rate_formula = nil, with_terms: false)
+        @rate_variable = parent_variable
+        @name = parent_variable.name
+        @terms = {}
+        @rate_function = rate_formula
+        @calculator = Keisan::Calculator.new(cache: true)
+      end
+
+      # Method to add a rate term. Automatically turns the existing rate function into another term to avoid mixing
+      # the two.
+      # @param [String] name The name of the rate term to be used for referencing
+      # @param [String] formula The mathematical expression for the term in native Ruby.
+      def add_rate_term(name, formula)
+        unless rate_function.nil?
+          @terms.store 'base_rate', DifferentialTerm.new('base_rate', rate_function, self)
+          @rate_function = nil
+        end
+        @terms&.store name, DifferentialTerm.new(name, formula, self)
+      end
+
+      # This part evaluates the derivative for the values provided.
+      # @param [Hash{String => Numeric}] values_hash The hash with the values of the variables and parameters
+      # @param [Integer] stage The stage of the Runge-Kutta method. Used to store the value in the proper array slot.
+      def derivative_value(values_hash, stage)
+        if @terms.empty?
+          @calculator.evaluate(@rate_function, values_hash)
+        else
+          @terms.values.reduce(0) do |sum, term|
+            contr = term.contribution(values_hash)
+            term.k_steps[stage] = contr
+            sum + contr
+          end
+        end
+      end
+
+      # It is common to have several distinct additive contributions to the derivatives of variables.
+      # This class enables to create different contributions (rate additive terms) that can be summed.
+      class DifferentialTerm
+        attr_accessor :name, :rate_function, :k_steps, :variable, :complementary, :last_mark, :last_interpol
+        # This is the change in the variable through the integration steps that is caused by the particular
+        # rate additive term. The sum of all rate additive terms is the variable step_change.
+        # @return [Float]
+        attr_accessor :step_change
+        # This attribute is necessary when a logging_interval is specified in order to track the total change
+        # between two logging points across steps.
+        # @return [Float]
+        attr_accessor :cumulative_change
+        # For dense output, tracks change not logged yet.
+        attr_accessor :lagging_change
+
+        def initialize(name, formula, equation)
+          @name = name
+          @rate_function = formula
+          @calculator = Keisan::Calculator.new(cache: true)
+          @variable = equation.rate_variable
+          @equation = equation
+          @cumulative_change, @lagging_change = 0, 0
+        end
+
+        # This part evaluates the contribution for the values provided. See {SubDifferentialEquation#derivative_value}.
+        # Called by the parent equation on each rate additive term to sum the contributions later.
+        def contribution(values_hash)
+          @calculator.evaluate(@rate_function, values_hash)
+        end
+
+        # Serializer to json for the overall DES json object.
+        def to_json(*_args)
+          { 'name' => name, 'rate_function' => rate_function }.to_json
+        end
+
+        # Provides value for dense output polynomial interpolation. For additive terms, only the step contribution is
+        # computed so starting value is zero by default.
+        # @return [Hash{Symbol => Numeric}] The hash with key value pairs.
+        def interpolator_hash
+          vals = { y0: 0, y1: step_change }
+          k_hash = k_steps.map.with_index { |k, i| ["k#{i + 1}".to_sym, k] }.to_h
+          vals.merge(k_hash)
+        end
+
+        # When writing the step change, adds to the cumulative change in order to keep total across the steps for
+        # logging.
+        def register_step_change(amount)
+          @step_change = amount
+          @cumulative_change += amount
+        end
+
+        # Gives the total cumulative change and resets it to zero for future logging
+        def report_and_reset
+          c = @cumulative_change
+          @cumulative_change = 0
+          c
+        end
+
+        # Gives the concatenation variable_name:term_name from the object itself.
+        def id = "#{variable.name}:#{name}"
+      end
+    end
+  end
+end

data/lib/bibun/log_entry.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Bibun
+  class DifferentialEquationSystem
+    class DifferentialEquationLogger
+      # Class to handle each column or quantity that is set to be logged (variables, terms, custom expressions...).
+      # Generic class. Only specific subclasses are meant to be instanced.
+      # Contains attributes for all subclasses to implement polymorphism
+      class LogEntry
+        # The array with the values at each row.
+        attr_accessor :values, :stepper, :logger, :tracker, :buffer_hash, :decimals, :type
+
+        # Standard initializer. Subclasses receive the object which are meant to track and log.
+        def initialize(logger, decimals)
+          @values  = []
+          @stepper = logger.system.stepper
+          @logger  = logger
+          @tracker = logger.tracker
+          @decimals = decimals
+        end
+
+        # Method to add one row value to the values array.
+        def register(marks = nil, index = nil)
+          values << loggable(marks, index).round(decimals)
+        end
+
+        # Shortcut method to access the values without having to type values each time.
+        def [](index)
+          values[index]
+        end
+
+        # Stub method for inheriting.
+        def loggable(marks, index); end
+
+        # Basic hash to be used for serializing to JSON.
+        def basic_hash(*_args)
+          { 'type' => @type, 'decimals' => @decimals }
+        end
+      end
+
+      # Subclass for logging values of variables
+      class VariableLogEntry < LogEntry
+        attr_reader :variable
+
+        def initialize(logger, decimals, var_name)
+          super(logger, decimals)
+          @variable = var_name
+          @type = 'variable'
+        end
+
+        # Asks the stepper for the value to log given the marks array and the index.
+        def loggable(marks,index) = stepper.variable_log_value(var_obj, marks, index)
+
+        # Necessary for logging the starting values
+        def register_value
+          values << logger.syms.variables[variable].value
+        end
+
+        # Quick way to get the variable object rather than its name.
+        def var_obj = logger.syms.variables[variable]
+
+        # Serializer for the outer class.
+        def to_json(*_args)
+          basic_hash.merge({ 'variable' => variable }).to_json
+        end
+      end
+
+      # Subclass to log rate additive terms
+      class TermLogEntry < LogEntry
+        attr_reader :variable, :term
+
+        def initialize(logger, decimals, var_name, term_name)
+          super(logger, decimals)
+          @variable = var_name
+          @term     = term_name
+          @type = 'term'
+        end
+
+        # Asks the stepper for the value to log providing the marks array and the index.
+        def loggable(marks, index)
+          stepper.term_log_value(term_obj, marks, index)
+        end
+
+        # Quick way to get the rate additive term object.
+        def term_obj = logger.syms.variables[variable].terms[term]
+
+        # Serializer to json
+        def to_json(*_args)
+          basic_hash.merge({ 'variable' => variable, 'term' => term }).to_json
+        end
+      end
+
+      # Subclass for logging the current step
+      class StepLogEntry < LogEntry
+        def initialize(logger, decimals)
+          super(logger, decimals)
+          @type = 'step'
+        end
+
+        # Gives the current logging step for logging.
+        def loggable(*args) = tracker.current_logging_step
+        # Serializer to JSON
+        def to_json(*_args) = basic_hash.to_json
+      end
+
+      # Subclass for logging custom math expressions.
+      class ExpressionLogEntry < LogEntry
+        # @return [String] The mathematical expression for Keisan in plain Ruby syntax.
+        attr_accessor :expression
+        # Unlike other entries, expressions require to know their name since it is custom made.
+        attr_accessor :name
+
+        def initialize(logger, decimals, name, expression)
+          super(logger, decimals)
+          @expression = expression
+          @calculator = Keisan::Calculator.new(cache: true)
+          @type = 'expression'
+          @name = name
+        end
+
+        # Gives the calculated value for the expression for logging.
+        def loggable(*args) = @calculator.evaluate(expression, buffer_hash)
+
+        # Serializer to JSON.
+        def to_json(*_args)
+          basic_hash.merge('name' => name, 'formula' => expression).to_json
+        end
+      end
+    end
+  end
+end