SymCalc Ruby Documentation
Not here for Ruby? You can choose another language
Here, you will see how SymCalc is structured and operates inside.
List of contents
SymCalc module
To organize SymCalc and prevent conflits, all further classes and functions are wrapped inside of the "SymCalc" module
You can include it like this:
require 'symcalc'
include SymCalc
Equation class
The Equation class is the back-bone of SymCalc. Equation is the base class of all other operation classes, as it outlines how a SymCalc class should be structured.
Methods
display()
Returns the text represantation of the expression, should be a string
to_s()
Returns self.display(), used to output a string when doing "puts equation"
coerce(other)
Returns the array of other converted to an equation and self
*(eq)
Returns a Multiplication object with self and eq
/(eq)
Returns a Division object with self and eq
+(eq)
Returns a Sum object with self and eq
-(eq)
Returns a Subtraction object with self and eq
**(eq)
Returns a Power object with self and eq
_derivative(variable: nil)
Implements the actual differentiation algorithm for self. If not implemented, raises an error
derivative(order: 1, variable: nil)
Wraps the _derivative() method with a specified order and implements checks on the specified variable.
_simplify()
Implements the actual simplification process of a SymCalc class. By default returns self.
simplify()
Wraps the _simplify() method and implements additional checks for multiplications and divisions.
_eval(var_hash)
Implements the actual evaluation process. Should return a numerical value. By default, raises an error
eval(var_hash)
Wraps the _eval() method, adding functionality for multiple evaluations by providing a array with values for each variable.
_sub(original, replacement)
Implements the check if original is equal to replacement and then outputs replacement, otherwise self.
sub(original, replacement)
Wraps the _sub() method, and simplifies the equation before returning.
Math operation classes
In this section are listed all 'operation' classes that inherit from Equation and override the structurally needed functions. These classes can have their own instance variables to implement different functionality, and all re-define the needed functions.
Variable
Implements the variable functionality in SymCalc
EquationValue
Acts as a numberical value, e.g. 5 or -152
Constant
Acts as a mathematical constant. Behaves like EquationValue during computations, but prints out as a variable
Sum
Implements the summation operation of two equations
Negate
Implements the subtraction operation between to equations
Multiplication
Implements the multiplication operation between two expressions
Division
Implements the division operation between two expressions
Power
Implements the mathematical power operation between two elements, a base and a power, e.g. base ^ power
Ln
Implements the natural logarithm operation
Log
Implements the logarithm operation
Exp
Implements the exponential function
Abs
Implements the absolute value function
Sin
Implements the sine function
Cos
Implements the cosine function
Operation methods
Operation methods create new SymCalc class objects in a more readable and comprehensible way. Here is the full list of them:
sin(eq)
Creates a sine equation
cos(eq)
Creates a cosine equation
ln(eq)
Creates a natural logarithm equation
log(base, eq)
Creates a log equation, where base and eq are log_base(eq)
exp(eq)
Creates an exponential equation
var(name, fixed_value=nil)
Creates a variable with a fixed value if specified
abs(eq)
Creates an absolute value equation
Helper methods
There are several functions that help with managing Equations.
to_equation(eq)
If eq is an Equation just returns it, otherwise returns the eq wrapped in an EquationValue
Constants
As previously mentioned, SymCalc has the ability to create constants that are a mix of EquationValue and Variable.
SymCalc has a few pre-defined constants that are located in the SymCalc::Constants module.
Here is a list of them:
Constants::E
Euler's number, the base of the natural log, or the limit of (1 + 1/n)^n as n tends to infinity.
Constants::Pi
Pi, the trigonometrical constant, that is equal to the ratio of a circle's circumference to its diameter.
Creating a new operation class
If any idea sparks your mind, it's possible to create a new SymCalc function with new features and ideas. Let's go over how to do it on an example of re-creating the absolute value function in SymCalc.
Our CustomAbs class has to inherit from the Equation class and re-define the functions in it. Let's start out by writing our class:
require 'symcalc'
# Include the SymCalc module
include SymCalc
class CustomAbs < Equation
attr_accessor :eq
def initialize eq
@eq = to_equation(eq)
end
def display
# Make a text representation
return "|#{@eq.display}|"
end
def __eval__ var_hash
# Evaluate the inside expression and take the absolute value
return @eq.eval(var_hash).abs
end
# Derivative function
# |f(x)|' = (f(x) / |f(x)|) * f'(x)
# Example:
# If f(x) = x, then
# |x|' = (x / |x|) * (x)' = (x / |x|) * 1 = x / |x|
def __derivative__ variable: nil
return @eq / CustomAbs.new(@eq) * @eq.derivative(variable: variable)
end
def __simplify__
# If the equation has a power that is divisible by two, return the expression inside
if @eq.is_a?(Power) && @eq.power.is_a?(EquationValue) && @eq.power.value.is_a?(Numeric) && (@eq.power.value % 2 == 0)
return @eq
end
self
end
def all_variables
# Return variables of the expression inside
return @eq.all_variables
end
def __sub__ original, replacement
return to_equation(replacement) if self == to_equation(original)
return CustomAbs.new(@eq._sub(original, replacement))
end
end
Next, let's write out an operation method that makes using our new class simpler:
# Create a custom_abs() method for easier expression definition when using SymCalc
def custom_abs eq
new_eq = CustomAbs.new(eq)
# Simplify, if the auto simplify option is true
new_eq = new_eq.simplify() if $SYMCALC_AUTO_SIMPLIFY
new_eq
end
Now we have our new CustomAbs class ready! Let's try using it:
require 'symcalc'
include SymCalc
# You can paste the new CustomAbs class and method here, or require relative a file with class definition
x = SymCalc.var "x"
fx = custom_abs(x - 4)
puts fx.eval(x: 3) # => 1
Other
There are some other configurations of SymCalc you could tweak to configure SymCalc how you want. Here is the list of them
SymCalc auto simplify option
The SymCalc auto simplify option is a boolean that is true by default. When the option is true, every new Equation created will simplify itself by default. Turning off this feature will tell SymCalc not to simplify equations when created.
Here is how you can change it:
$SYMCALC_AUTO_SIMPLIFY = false
# or
$SYMCALC_AUTO_SIMPLIFY = true // the default option
Well, that's the end of SymCalc's documentation! Thank you for reading it and getting involved with SymCalc!
If you have any question or ideas about SymCalc, you can contact me on my portfolio website, or by email.
SymCalc is licensed under the Apache 2.0 license. You can read more on the about page.