NAME
Math::Symbolic::Custom::Equation - Work with equations of Math::Symbolic expressions
VERSION
Version 0.2
DESCRIPTION
This class implements methods for equating two Math::Symbolic expressions, and performing various operations on that equation.
EXAMPLE
use strict;
use Math::Symbolic 0.613 qw(:all);
use Math::Symbolic::Custom::Equation 0.2;
use Math::Symbolic::Custom::Polynomial 0.3;
use Math::Symbolic::Custom::CollectSimplify 0.2;
Math::Symbolic::Custom::CollectSimplify->register();
# Solve the simultaneous equations:-
# x - 2*y = 7
# x^2 + 4*y^2 = 37
my $eq1 = Math::Symbolic::Custom::Equation->new('x - 2*y = 7');
my $eq2 = Math::Symbolic::Custom::Equation->new('x^2 + 4*y^2 = 37');
print "Solve the simultaneous equations:-\n\n";
print "\t[1]\t", $eq1->to_string(), "\n";
print "\t[2]\t", $eq2->to_string(), "\n\n";
# Make x the subject of eq. 1
my $eq1_x = $eq1->isolate('x');
die "Cannot isolate 'x' in " . $eq1->to_string() . "\n" unless defined $eq1_x;
print "Make x the subject of [1]: ", $eq1_x->to_string(), "\n\n";
my $x_expr = $eq1_x->RHS();
# Substitute into eq. 2, re-arrange to make RHS = 0, and simplify
my $eq3 = $eq2->implement('x' => $x_expr)->simplify();
print "Substitute into [2]: ", $eq3->to_string(), "\n\n";
# Re-arrange it to equal 0
my $eq3_2 = $eq3->to_zero()->simplify();
print "Rearrange to equal zero: ", $eq3_2->to_string(), "\n\n";
# we have an expression for y, solve it
my ($var, $coeffs, $disc, $roots) = $eq3_2->LHS()->test_polynomial();
die "Cannot solve quadratic!\n" unless defined($var) && ($var eq 'y');
my $y_1 = $roots->[0];
my $y_2 = $roots->[1];
print "The solutions for y are: ($y_1, $y_2)\n\n";
# put these solutions into the expression for x in terms of y to get x values
my $x_1 = $eq1_x->implement('y' => $y_1)->simplify()->RHS();
my $x_2 = $eq1_x->implement('y' => $y_2)->simplify()->RHS();
print "The solutions for x given y are: (x = $x_1 when y = $y_1) and (x = $x_2 when y = $y_2)\n\n";
# Check that these solutions hold for the original equations
print "Check: ";
if ( $eq1->holds({'x' => $x_1, 'y' => $y_1}) && $eq2->holds({'x' => $x_1, 'y' => $y_1}) ) {
print "Solution (x = $x_1, y = $y_1) holds for [1] and [2]\n";
}
print "Check: ";
if ( $eq1->holds({'x' => $x_2, 'y' => $y_2}) && $eq2->holds({'x' => $x_2, 'y' => $y_2}) ) {
print "Solution (x = $x_2, y = $y_2) holds for [1] and [2]\n";
}METHODS
Constructor new
Expects the left hand side and right hand side of the desired equation as parameters. These can be Math::Symbolic expressions, or strings which will be parsed into Math::Symbolic expressions using the parser. Another option is to pass one parameter, an equation string, from which the left hand side and the right hand side of the equation will be extracted.
# specify LHS and RHS separately
my $eq1 = Math::Symbolic::Custom::Equation->new('y', '2*x + 4');
# pass it an equation
my $eq2 = Math::Symbolic::Custom::Equation->new('y = 2*x + 4');Method LHS
With no parameter, will return the left-hand side of the equation. With a parameter, will set the left-hand side of the equation, and return it.
Method RHS
With no parameter, will return the right-hand side of the equation. With a parameter, will set the right-hand side of the equation, and return it.
Method to_string
Takes no parameter. Will return the equation in string form, e.g. "LHS = RHS".
Method holds
Tests to see if the equation is true for given variable values, passed as a hash reference. This calls Math::Symbolic's value() method with the passed values on the expressions for the left-hand side and right-hand side and compares the two results.
An optional second argument is a threshold used to set the accuracy of the numerical comparison (set by default to 1e-11).
my $eq = Math::Symbolic::Custom::Equation->new('y', '2*x + 4');
if ( $eq->holds({'x' => 2, 'y' => 8}) ) {
print "'", $eq->to_string(), "' holds for x = 2 and y = 8.\n";
# 'y = (2 * x) + 4' holds for x = 2 and y = 8.
} Method simplify
Takes no parameters. Calls Math::Symbolic's simplify() (or whichever simplify() is currently registered) on both sides of the equation. If successful returns a new (simplifed) equation object, otherwise undef.
Method implement
Calls Math::Symbolic's implement() on both sides of the equation. This can be used to substitute a specified variable with another Math::Symbolic expression (see the example above). If successful returns a new equation object, otherwise undef.
Method add
Takes one parameter, which can be another equation object, or a Math::Symbolic expression (or a text string which can parse to a Math::Symbolic expression). If passed an equation then it will perform equation addition, or if passed an expression it will add the passed expression to both sides of the equation. Returns a new equation object.
Method subtract
Takes one parameter, which can be another equation object, or a Math::Symbolic expression (or a text string which can parse to a Math::Symbolic expression). If passed an equation then it will perform equation subtraction, or if passed an expression it will subtract the passed expression to from sides of the equation. Returns a new equation object.
Method multiply
Takes one parameter, a Math::Symbolic expression or a text string which can parse to a Math::Symbolic expression.
Multiplies the passed expression with both sides of the equation and returns a new equation object.
Method divide
Takes one parameter, a Math::Symbolic expression or a text string which can parse to a Math::Symbolic expression.
Divides both sides of the equation by the passed expression and returns a new equation object.
Method to_zero
Takes no parameters. Re-arranges the equation to equate to zero, by subracting the right-hand side from both sides. Returns a new equation object.
my $eq = Math::Symbolic::Custom::Equation->new('3*x^3 - 2*x^2 + 5*x - 10 = 5*x + 8');
$eq->to_zero();
print $eq->to_string(), "\n"; # ((3 * (x ^ 3)) - 18) - (2 * (x ^ 2)) = 0Method explicit_signature
Takes no parameters. Calls Math::Symbolic's explicit_signature() on both sides of the equation and returns the de-duped results, effectively returning a list of variables used in the equation.
my $eq = Math::Symbolic::Custom::Equation->new('y', '2*x + 4');
my @vars = $eq->explicit_signature();
print "Vars: ('", join("', '", sort {$a cmp $b } @vars), "')\n"; # Vars: ('x', 'y')Method isolate
Takes a Math::Symbolic::Variable, or a string which parses to a Math::Symbolic::Variable, as a parameter. This method attempts to re-arrange the equation to make that variable the subject of the equation, returning new equation object(s). It will return undef if it doesn't succeed.
When called in a scalar context, it will return the first (simplest) result it can find. When called in a list context it will return all the results it can find.
my $eq = Math::Symbolic::Custom::Equation->new('v^2 = u^2 + 2*a*s');
my $hit = $eq->isolate('u');
print "Result 1: ", $hit->to_string(), "\n\n";
# Result 1: u = ((v ^ 2) - ((2 * a) * s)) ^ (1 / 2)
my @hits = $eq->isolate('u');
foreach my $hit (@hits) {
print "Result 2: ", $hit->to_string(), "\t";
}
# Result 2: u = ((v ^ 2) - ((2 * a) * s)) ^ (1 / 2)
# Result 2: u = -1 * (((v ^ 2) - ((2 * a) * s)) ^ (1 / 2))Warning: this is very different to how it worked in the previous version of the module, and it probably has a way to go yet.
SEE ALSO
AUTHOR
Matt Johnson, <mjohnson at cpan.org>
ACKNOWLEDGEMENTS
Steffen Mueller, author of Math::Symbolic
LICENSE AND COPYRIGHT
This software is copyright (c) 2025 by Matt Johnson.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.