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.