Extensive documentation writing and testing

polymani.pl

@@ -19,7 +19,8 @@
  * https://doi.org/10.1017/S1471068411000391 *
  *********************************************/
 
-/* Import the Constraint Logic Programming over Finite Domains library
+/*
+ * Import the Constraint Logic Programming over Finite Domains library
  * Essentially, this library improves the way Prolog deals with integers,
  * allowing more predicates to be reversible.
  * For instance, number(N) is always false, which prevents the
@@ -38,6 +39,7 @@
     argument) and vice-versa.
 */
 poly2list(P, L) :-
+    is_term_valid_in_predicate(P, "poly2list"),
     polynomial_to_list(P, L),
     !.
 
@@ -46,6 +48,7 @@ poly2list(P, L) :-
     another polynomial as a list.
 */
 simpoly_list(L, S) :-
+    is_polynomial_list_valid_in_predicate(L, "simpoly_list"), %TODO IMPLEMENT
     simplify_polynomial_as_list(L, S),
     !.
 
@@ -54,6 +57,7 @@ simpoly_list(L, S) :-
     as another polynomial as an expression.
 */
 simpoly(P, S) :-
+    is_term_valid_in_predicate(P, "simpoly"),
     simplify_polynomial(P, S),
     !.
 
@@ -63,6 +67,8 @@ simpoly(P, S) :-
     be ground. The polynomial resulting from the sum is in simplified form.
 */
 scalepoly(P1, P2, S) :-
+    is_term_valid_in_predicate(P1, "scalepoly"),
+    is_term_valid_in_predicate(P2, "scalepoly"),
     scale_polynomial(P1, P2, S),
     !.
 
@@ -72,6 +78,8 @@ scalepoly(P1, P2, S) :-
     The polynomial resulting from the sum is in simplified form.
 */
 addpoly(P1, P2, S) :-
+    is_term_valid_in_predicate(P1, "addpoly"),
+    is_term_valid_in_predicate(P2, "addpoly"),
     add_polynomial(P1, P2, S),
     !.
 
@@ -86,7 +94,7 @@ addpoly(P1, P2, S) :-
 %
 polynomial_variable_list([x, y, z]).
 
-%% polynomial_variable(?X:atom) is det
+%% polynomial_variable(?X:atom) is semidet
 %
 %  Returns true if X is a polynomial variable, false otherwise.
 %
@@ -135,20 +143,27 @@ power(X) :-
 %@ X = y ;
 %@ X = z.
 
-%% term(+N:atom) is det
+%% term(+N:atom) is semidet
 %
 %  Returns true if N is a term, false otherwise.
 %
 term(N) :-
-    %% number(N).
+    (
-    (nonvar(N),
+	% If N is non a free variable
-     number(N));
+	nonvar(N),
-    (not(compound(N)),
+	% Assert it as a number
+	number(N)
+    );
+    (
+	% If N is a free variable
+	not(compound(N)),
 	var(N),
-     N in inf..sup).
+	% Assert it must be between negative and positive infinity
-    %% {N >= -1000, N =< 1000}.
+	% This uses the CLP(FD) library, which makes this reversible,
-    %% N ::= inf..sup.
+	% whereas `number(N)` is always false, since it only succeeds
-    %% (var(N), N in inf..sup).
+	% if the argument is bound to a intger or float
+	N in inf..sup
+    ).
 term(X) :-
     power(X).
 term(L * R) :-
@@ -200,28 +215,37 @@ term(L * R) :-
 %  The fail message reports which Term is invalid and in which
 %  predicate the problem ocurred.
 %
-is_term_valid_in_predicate(T, F) :-
+is_term_valid_in_predicate(P, _) :-
-    (
+    %% If P is a valid polynomial, return true
-        term(T)
+    polynomial(P),
-    ;
+    !.
-        write("Invalid term in "),
+is_term_valid_in_predicate(P, F) :-
+    %% Writes the polynomial and fails otherwise
+    write("Invalid polynomial in "),
     write(F),
     write(": "),
-        write(T),
+    write(P),
-        fail
+    fail.
-    ).
 %% Tests:
 %% ?- is_term_valid_in_predicate(1, "Test").
-%@ true .
+%@ true.
-%% ?- is_term_valid_in_predicate(a, "Test").
+%% ?- is_term_valid_in_predicate(a*4-0*x, "Test").
+%@ Invalid polynomial in Test: a*4-0*x
+%@ false.
 
-%% polynomial(+M:atom) is det
+%% polynomial(+M:atom) is semidet
 %
 %  Returns true if polynomial, false otherwise.
 %
 polynomial(M) :-
+    %% A polynomial is either a term
     term(M).
 polynomial(L + R) :-
+    %% Or a sum of terms
+    polynomial(L),
+    term(R).
+polynomial(L - R) :-
+    %% Or a subtraction of terms
     polynomial(L),
     term(R).
 %% Tests:
@@ -233,17 +257,21 @@ polynomial(L + R) :-
 %@ true .
 %% ?- polynomial(2 + 3*x + 4*x*y^3).
 %@ true .
+%% ?- polynomial(2 - 3*x + 4*x*y^3).
+%@ true .
 %% ?- polynomial(a).
 %@ false.
 %% ?- polynomial(x^(-3)).
 %@ false.
 
-%% power_to_canon(+T:atom, -T^N:atom) is det
+%% power_to_canon(+T:atom, -T^N:atom) is semidet
 %
 %  Returns a canon power term.
 %
 power_to_canon(T^N, T^N) :-
     polynomial_variable(T),
+    % CLP(FD) operator to ensure N is different from 1,
+    % in a reversible way
     N #\= 1.
 power_to_canon(T, T^1) :-
     polynomial_variable(T).
@@ -259,9 +287,11 @@ power_to_canon(T, T^1) :-
 %% ?- power_to_canon(X, x^(-3)).
 %@ X = x^ -3 .
 
-%% term_to_list(?T, ?List) is det
+%% term_to_list(?T, ?List) is semidet
 %
 %  Converts a term to a list and vice versa.
+%  A term is multiplication of a number or a power
+%  and another term
 %  Can verify if term and list are compatible.
 %
 term_to_list(L * N, [N | TS]) :-
@@ -285,19 +315,20 @@ term_to_list(P, [P2]) :-
 %@ X = [3, 2] .
 %% ?- term_to_list(1*2*y*z*23*x*y*x^3*x, X).
 %@ X = [x^1, x^3, y^1, x^1, 23, z^1, y^1, 2, 1] .
+%% ?- term_to_list(1*2*y*z*23*x*y*(-1), X).
+%@ X = [-1, y^1, x^1, 23, z^1, y^1, 2, 1] .
 %% ?- term_to_list(X, [-1]).
 %@ X = -1 .
 %% ?- term_to_list(X, [x^1, -1]).
 %@ X = -1*x .
-%% ?- term_to_list(X, [- 1, x^1]).
-%@ false.
-%@ X = x* -1 .
 %% ?- term_to_list(X, [y^1, x^1]).
 %@ X = x*y .
 %% ?- term_to_list(X, [x^4]).
 %@ X = x^4 .
 %% ?- term_to_list(X, [y^6, z^2, x^4]).
 %@ X = x^4*z^2*y^6 .
+%% ?- term_to_list(X, [y^6, z^2, x^4, -2]).
+%@ X = -2*x^4*z^2*y^6 .
 
 %% simplify_term(+Term_In:term, ?Term_Out:term) is det
 %
@@ -305,18 +336,27 @@ term_to_list(P, [P2]) :-
 %
 simplify_term(Term_In, Term_Out) :-
     term_to_list(Term_In, L),
+    %% Sort the list of numbers and power to group them,
+    %% simplifying the job of `join_similar_parts_of_term`
     sort(0, @=<, L, L2),
     (
+	%% If there's a 0 in the list, then the whole term is 0
         member(0, L2),
         Term_Out = 0
     ;
+        %% Otherwise
         (
+	    %% If there's only one element, then the term was already simplified
+	    %% This is done so that the `exclude` following doesn't remove all ones
             length(L2, 1),
             Term_Out = Term_In
         ;
+ 	    %% Remove all remaining ones
             exclude(==(1), L2, L3),
             join_similar_parts_of_term(L3, L4),
-            sort(0, @>=, L4, L5),
+            %% Reverse the list, since the following call gives the result in the
+	    %% reverse order otherwise
+	    reverse(L4, L5),
             term_to_list(Term_Out, L5)
         )
     ),
@@ -334,30 +374,41 @@ simplify_term(Term_In, Term_Out) :-
 %% ?- simplify_term(0*y*z*x^3*x, X).
 %@ X = 0.
 %% ?- simplify_term(6*y*z*7*x*y*x^3*x, X).
-%@ X = 42*x^2*x^3*y^2*z.
+%@ X = 42*x^5*y^2*z.
 %% ?- simplify_term(a, X).
 %@ false.
 %% ?- simplify_term(x^(-3), X).
 %@ false.
 
-%% join_similar_parts_of_term(+List, -List)
+%% join_similar_parts_of_term(+List, -List) is det
 %
 %  Combine powers of the same variable in the given list
 %
 join_similar_parts_of_term([P1, P2 | L], L2) :-
+    %% If both symbols are powers
     power(P1),
     power(P2),
+    %% Decompose them into their parts
     B^N1 = P1,
     B^N2 = P2,
+    %% Sum the exponent
     N is N1 + N2,
-    join_similar_parts_of_term([B^N | L], L2).
+    join_similar_parts_of_term([B^N | L], L2),
+    % First result is always the most simplified form.
+    !.
 join_similar_parts_of_term([N1, N2 | L], L2) :-
+    %% If they are both numbers
     number(N1),
     number(N2),
+    %% Multiply them
     N is N1 * N2,
-    join_similar_parts_of_term([N | L], L2).
+    join_similar_parts_of_term([N | L], L2),
+    % First result is always the most simplified form.
+    !.
 join_similar_parts_of_term([X | L], [X | L2]) :-
-    join_similar_parts_of_term(L, L2).
+    join_similar_parts_of_term(L, L2),
+    % First result is always the most simplified form.
+    !.
 join_similar_parts_of_term([], []).
 %% Tests:
 %% ?- join_similar_parts_of_term([3], T).
@@ -365,22 +416,25 @@ join_similar_parts_of_term([], []).
 %% ?- join_similar_parts_of_term([x^2], T).
 %@ T = [x^2].
 %% ?- join_similar_parts_of_term([x^1, x^1, x^1, x^1], T).
-%@ T = [x^4] .
+%@ T = [x^4].
 %% ?- join_similar_parts_of_term([2, 3, x^1, x^2], T).
-%@ T = [6, x^3] .
+%@ T = [6, x^3].
 %% ?- join_similar_parts_of_term([2, 3, x^1, x^2, y^1, y^6], T).
-%@ T = [6, x^3, y^7] .
+%@ T = [6, x^3, y^7].
 
 %% simplify_polynomial(+P:atom, -P2:atom) is det
 %
 %  Simplifies a polynomial.
 %
 simplify_polynomial(0, 0) :-
+    % 0 is already fully simplified and is an
+    % exception to the following algorithm
     !.
 simplify_polynomial(P, P2) :-
     polynomial_to_list(P, L),
     simplify_polynomial_as_list(L, L2),
     list_to_polynomial(L2, P2),
+    %% The first result is the most simplified one
     !.
 %% Tests:
 %% ?- simplify_polynomial(1, X).
@@ -403,11 +457,45 @@ simplify_polynomial(P, P2) :-
 %@ X = 6*x^3.
 %% ?- simplify_polynomial(x^2*x + 3*x^3 + x^3 + x*x*4 + z, X).
 %@ X = 5*x^3+4*x^2+z.
+%% ?- simplify_polynomial(x^2*x + 3*x^3 - x^3 - x*x*4 + z, X).
+%@ X = 3*x^3-4*x^2+z.
 %% ?- simplify_polynomial(x + 1 + x, X).
 %@ X = 2*x+1.
 %% ?- simplify_polynomial(x + 1 + x + 1 + x + 1 + x, X).
 %@ X = 4*x+3.
 
+%% simplify_polynomial_as_list(+L1:List,-L3:List) is det
+%
+%  Simplifies a polynomial represented as a list
+%
+simplify_polynomial_as_list(L, L11) :-
+    %% Convert each term to a list
+    maplist(term_to_list, L, L2),
+    %% Sort each sublist; done so the next
+    %% sort gives the correct results
+    maplist(sort(0, @>=), L2, L3),
+    %% Sort the outer list
+    sort(0, @>=, L3, L4),
+    %% For each of the parts of the terms, join them
+    maplist(join_similar_parts_of_term, L4, L5),
+    %% Sort each of the sublists
+    %% Done so the next call simplifies has less work
+    maplist(sort(0, @=<), L5, L6),
+    join_similar_terms(L6, L7),
+    %% Reverse each sublist, because the next call
+    %% reverses the result
+    maplist(reverse, L7, L8),
+    maplist(term_to_list, L9, L8),
+    %% Delete any 0 from the list
+    delete(L9, 0, L10),
+    %% Sort list converting back gives the result in the correct order
+    sort(0, @=<, L10, L11).
+%% Tests:
+%% ?- simplify_polynomial_as_list([x, 1, x^2, x*y, 3*x^2, 4*x], L).
+%@ L = [1, 4*x^2, 5*x, x*y] .
+%% ?- simplify_polynomial_as_list([1, x^2, x*y, 3*x^2, -4, -1*x], L).
+%@ L = [-3, -1*x, 4*x^2, x*y] .
+
 %% join_similar_terms(+P:ListList, -P2:ListList) is det
 %
 %  Joins similar sublists representing terms by using
@@ -449,6 +537,13 @@ term_to_canon([T | TS], [1, T | TS]) :-
     not(number(T)),
     %% Give only first result. Red cut
     !.
+term_to_canon([T | TS], [N, T | TS]) :-
+    %% Since the list is sorted, if the first element
+    %% is not a number, then we need to add the 1
+    not(number(T)),
+    N is -1,
+    %% Give only first result. Red cut
+    !.
 term_to_canon(L, L).
 %% Tests:
 %% ?- term_to_canon([2], T).
@@ -467,9 +562,13 @@ term_to_canon(L, L).
 %  Requires the list of terms to be simplified.
 %
 add_terms([NL | TL], [NR | TR], [N2 | TL2]) :-
+    %% Convert each term to a canon form. This ensures they
+    %% have a number in front, so it can be added
     term_to_canon([NL | TL], [NL2 | TL2]),
     term_to_canon([NR | TR], [NR2 | TR2]),
+    %% If they rest of the term is the same
     TL2 == TR2,
+    %% Add the coeficients
     N2 is NL2 + NR2.
 %% Tests
 %% ?- add_terms([1], [1], R).
@@ -481,22 +580,6 @@ add_terms([NL | TL], [NR | TR], [N2 | TL2]) :-
 %% ?- add_terms([2, x^3], [3, x^3], R).
 %@ R = [5, x^3].
 
-%% simplify_polynomial_as_list(+L1:List,-L3:List) is det
-%
-%  Simplifies a polynomial represented as a list
-%
-simplify_polynomial_as_list(L, L11) :-
-    maplist(term_to_list, L, L2),
-    maplist(sort(0, @>=), L2, L3),
-    sort(0, @>=, L3, L4),
-    maplist(join_similar_parts_of_term, L4, L5),
-    maplist(sort(0, @=<), L5, L6),
-    join_similar_terms(L6, L7),
-    maplist(reverse, L7, L8),
-    maplist(term_to_list, L9, L8),
-    delete(L9, 0, L10),
-    sort(0, @=<, L10, L11).
-
 %% polynomial_to_list(+P:polynomial, -L:List) is det
 %
 %  Converts a polynomial in a list.
@@ -529,7 +612,7 @@ polynomial_to_list(T, [T]) :-
 %% ?- polynomial_to_list(2*x^2+3*x+5*x^17-7*x^21+3*x^3-23*x^4+25*x^5-4.3, S).
 %@ S = [-4.3, 25*x^5, -23*x^4, 3*x^3, -7*x^21, 5*x^17, 3*x, 2* ... ^ ...].
 
-%% list_to_polynomial(+P:polynomial, -L:List)
+%% list_to_polynomial(+P:polynomial, -L:List) is det
 %
 %  Converts a list in a polynomial.
 %
@@ -555,7 +638,8 @@ list_to_polynomial([T1|T2], P) :-
 list_to_polynomial(T, P) :-
     P = T.
 %% Tests:
-%% TODO
+%% ?- list_to_polynomial([1, x, x^2], P).
+%@ P = x^2+x+1.
 
 %% negate_term(T, T2) is det
 %
@@ -563,12 +647,16 @@ list_to_polynomial(T, P) :-
 %
 negate_term(T, T2) :-
     term_to_list(T, L),
+    %% Sort the list, so the coeficient is the first element
     sort(0, @=<, L, L2),
+    %% Ensure there is a coeficient
     term_to_canon(L2, L3),
     [N | R] = L3,
     %% (-)/1 is an operator, needs to be evaluated, otherwise
     %% it gives a symbolic result, which messes with further processing
     N2 is -N,
+    %% Reverse the order of the list, because converting
+    %% implicitly reverses it
     reverse([N2 | R], L4),
     term_to_list(T2, L4),
     !.
@@ -584,13 +672,17 @@ negate_term(T, T2) :-
 
 %% scale_polynomial(+P:polynomial,+C:constant,-S:polynomial) is det
 %
-%  Scales a polynomial with a constant
+%  Multiplies a polynomial by a scalar
 %
 scale_polynomial(P, C, S) :-
     polynomial_to_list(P, L),
+    %% Convert each term to a list
     maplist(term_to_list, L, L2),
+    %% Append C to the start of each sublist
     maplist(cons(C), L2, L3),
+    %% Convert back
     maplist(term_to_list, L4, L3),
+    %% Simplify the resulting polynomial
     simplify_polynomial_as_list(L4, L5),
     list_to_polynomial(L5, S),
     !.
@@ -609,10 +701,14 @@ cons(C, L, [C | L]).
 %  S = P1 + P2
 %
 add_polynomial(P1, P2, S) :-
+    %% Convert both polynomials to lists
     polynomial_to_list(P1, L1),
     polynomial_to_list(P2, L2),
+    %% Join them
     append(L1, L2, L3),
+    %% Simplify the resulting polynomial
     simplify_polynomial_as_list(L3, L4),
+    %% Convert back
     list_to_polynomial(L4, S),
     !.
 %% Tests: