From 4fb5bd5a645de30f01120f8892a95cc767293715 Mon Sep 17 00:00:00 2001
From: "Vladimir V. Kisil" <V.Kisilv@leeds.ac.uk>
Date: Sun, 6 Jun 2021 09:32:31 +0100
Subject: [PATCH 2/2] Add method relational::canonical

It returns an equivalent relation with the zero right-hand side.

Signed-off-by: Vladimir V. Kisil <V.Kisilv@leeds.ac.uk>
---
 doc/tutorial/ginac.texi | 20 +++++++++++++++++++-
 ginac/relational.cpp    |  7 +++++++
 ginac/relational.h      |  2 ++
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 40fa5624..d52e422b 100644
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -1866,13 +1866,31 @@ substitutions.  They are also used as arguments to the @code{ex::series}
 method, where the left hand side of the relation specifies the variable
 to expand in and the right hand side the expansion point.  They can also
 be used for creating systems of equations that are to be solved for
-unknown variables.  But the most common usage of objects of this class
+unknown variables.
+
+But the most common usage of objects of this class
 is rather inconspicuous in statements of the form @code{if
 (expand(pow(a+b,2))==a*a+2*a*b+b*b) @{...@}}.  Here, an implicit
 conversion from @code{relational} to @code{bool} takes place.  Note,
 however, that @code{==} here does not perform any simplifications, hence
 @code{expand()} must be called explicitly.
 
+Simplifications of
+relationals may be more efficient if preceded by a call to
+@example
+ex relational::canonical() const
+@end example
+which returns an equivalent relation with the zero
+right-hand side. For example:
+@example
+possymbol p("p");
+relational rel = (p >= (p*p-1)/p);
+if (ex_to<relational>(rel.canonical().normal()))
+	cout << "correct inequality" << endl;
+@end example
+However, a user shall not expect that any inequality can be fully
+resolved by GiNaC.
+
 @node Integrals, Matrices, Relations, Basic concepts
 @c    node-name, next, previous, up
 @section Integrals
diff --git a/ginac/relational.cpp b/ginac/relational.cpp
index 892d2e91..d050b2e6 100644
--- a/ginac/relational.cpp
+++ b/ginac/relational.cpp
@@ -348,4 +348,11 @@ relational::operator relational::safe_bool() const
 	}
 }
 
+/** Returns an equivalent relational with zero right-hand side.
+ */
+ex relational::canonical() const
+{
+	return relational(lh-rh, _ex0, o);
+}
+
 } // namespace GiNaC
diff --git a/ginac/relational.h b/ginac/relational.h
index b935a7ed..a9b072a7 100644
--- a/ginac/relational.h
+++ b/ginac/relational.h
@@ -63,6 +63,8 @@ public:
 	void archive(archive_node& n) const override;
 	/** Read (a.k.a. deserialize) object from archive. */
 	void read_archive(const archive_node& n, lst& syms) override;
+	ex canonical() const;
+
 protected:
 	ex eval_ncmul(const exvector & v) const override;
 	bool match_same_type(const basic & other) const override;
-- 
2.30.2