-
Notifications
You must be signed in to change notification settings - Fork 1
/
ries.1
1998 lines (1729 loc) · 81.9 KB
/
ries.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
'\" et
.TH RIES 1 "Manual version: 2022 Oct" \" -*- nroff -*-
.\"
.\" This manpage uses the groff font family escape, as documented here:
.\"
.\" gnu.org/software/groff/manual/html_node/Font-Families.html
.\"
.\" If your system cannot handle it, you can get this manual in several
.\" other formats from:
.\"
.\" mrob.com/ries
.\"
.SH NAME
ries \- find algebraic equations, given their solution
.SH SYNOPSIS
\fBries\fR
[\fB-l\fIn\fR] [\fB-i[e]\fR] [\fB-s\fR] [\fB-x\fR] [\fB-F\fIn\fR]
[\fB-S\fIsss\fR] [\fB-N\fIsss\fR] [\fB-O\fIsss\fR]
[\fB-D\fIxxx\fR] [\fB-p\fIfilename\fR]
[\fB--extended-options\fR [...]] \fIvalue\fR
.B ries --find-expression \fR[\fIexpression\fR [...]]
.B ries --eval-expression \fR[\fIexpression\fR [...]]
.SH DESCRIPTION
Given a number, \fBries\fR searches for algebraic equations in one
variable that have a solution (root) near that number. It avoids
trivial or reducible solutions like ``\fIx\fR/\fIx\fR = 1''. If
\fIvalue\fR is an integer, \fBries\fR can find an exact solution
expressed in terms of single-digit integers.
For example, if you supply the value 2.5063, the first part of
\fBries\fR's output will resemble the following:
.fam C
.ps -2
$ ries 2.5063
Your target value: T = 2.5063 mrob.com/ries
2 x = 5 for x = T - 0.0063 {49}
8 x = e^3 for x = T + 0.00439212 {66}
x^2 = 2 pi for x = T + 0.000328275 {55}
x^x = 1+9 for x = T - 0.000115854 {69}
x^2+e = 9 for x = T + 3.56063e-05 {63}
ln(6) x = sqrt(pi)+e for x = T + 2.73037e-05 {93}
x/4+1 = 4,/7 for x = T + 6.24679e-06 {91}
sinpi(ln(x))^2 = 1/(5 pi) for x = T + 2.75665e-06 {92}
.ps +2
.fam T
The output gives progressively ``more complex'' solutions (as described
below) that come progressively closer to matching your number. There
are four columns: equations in symbolic form (two columns of
expressions with `=' in the middle), solution of equation (value of
\fIx\fR expressed as \fIT\fR plus a small error term), and total complexity
score (described below).
Each match is checked by solving for \fIx\fR using the Newton-Raphson
method, and the closeness of the match is judged by the difference
between the root (the value of \fIx\fR for which the two sides are
equal) and your target value \fIT\fR.
Options allow complete control over what symbols, constants
and functions are used in solutions, or to limit solutions to
integer, rational, constuctible, or algebraic values.
.SH OPTIONS
Options must be separate: `\fCries -l1 -i -Ox 27\fR',
not `\fCries -l1iOx 27\fR'.
.IP \fB-p\fIname\fR
Profile (or Parameters): Load one or more options from file
\fIname\fR. \fB-p\fIname\fR is equivalent to \fB--include\fR
\fIname\fR, which is described in the EXTENDED OPTIONS section below.
\fB-p\fR alone (with no \fIname\fR) has special meanings, also
described under \fB--include\fR.
.IP \fB-l\fIn\fR
Level: Specifies the level of the search (default 2).
With each increment of \fB-l\fR, \fBries\fR
will search about 10 times as many equations, use
3.5 times as much memory and take at least 4 times as long.
Use higher levels to add more factors of 10.
The level can be fractional or negative.
Here are typical figures, measured on a Core i7 at 3.2 GHz
(using only one thread) invoked by the command
\fBries -l\fR\fIn\fR\fB 2.5063141592653589\fR
for different values of searchlevel \fIn\fR:
.fam C
.ps -2
memory equations tested digits run time
-l0 1.2M 89,400,000 6+ 0.025 sec
-l1 4.0M 932,000,000 7+ 0.08 sec
-l2 14 M 11,400,000,000 8+ 0.33 sec
-l3 45 M 134,000,000,000 9+ 1.8 sec
-l4 158M 1,600,000,000,000 11+ 8.8 sec
-l5 490M 15,000,000,000,000 12+ 37.1 sec
-l6 1.7G 184,000,000,000,000 13+ 190 sec
.ps +2
.fam T
(these times are a little quicker than a 2.33-GHz Core 2 Duo; on a
733-MHz Pentium 3, the times were about 5 times longer. If compiled
for an environment with 32-bit pointers, memory usage figures are about 20% lower.
\fBries\fR also works on much older and smaller systems, and can test
billions of equations in less than a minute on 1990's hardware)
Use a fractional argument (like \fB-l5.5\fR) for more precise control
of how much memory \fBries\fR will use before stopping its search.
When free memory is exhausted; performance will degrade significantly
and \fBries\fR might exit, depending on your operating system. Under
Linux and Mac OS, \fBries\fR keeps running but the system slows to a
crawl.
If you don't know what your OS will do, be careful before running
\fBries\fR with higher levels. In extreme cases your computer's
response might slow down so much that you are unable to save your work in
other applications.
The memory limits are not reached nearly as quickly when the symbolset
is greatly limited with \fB-S\fR, \fB-O\fR and \fB-N\fR or when
\fB-i\fR is specified. \fB-i\fR in particular should allow about two
more levels in any given amount of memory. Large arguments tend to
lengthen runtime: for example, \FCries -l4 1058073667\FT takes about
three times as long as \FCries -l4 1.058073667\FT.
.SH Options to Select Symbols
Several options are used to choose which symbols (constants,
operations, and functions) \fBries\fR is allowed to use when searching
for equations.
.IP \fB-N\fIsss\fR
Never use these: \fB-N\fR followed by one or more characters specifies
symbols (constants and operators) that \fBries\fR
should not use in its equations. The symbols are as follows:
.RS 0.7i
.IP 1-9
The integers 1 through 9. (\fBries\fR constructs all larger
integers from combinations of these.)
.IP p
pi = 3.14159...
.IP e
e = 2.71828...
.IP f
phi = (1+sqrt(5))/2 = 1.61803...
.IP n
Negative
.IP r
Reciprocal
.IP s
Squared
.IP q
Square root
.IP "S C"
Sine, Cosine
.IP T
Tangent
.IP A
Two-argument Arctangent: arctan(y,x) is the angle of the ray from the origin through the point (x,y)
.IP l
ln (natural logarithm, also called log)
.IP E
e to the power of x
.IP "+ -"
Add, Subtract
.IP "* /"
Multiply, Divide
.IP ^
Power: 2 ^ 3 = 8
.IP v
Root (the ``v'' resembles part of the radical symbol): 3 v 27 = cube root of 27
.IP L
Logarithm to base A of B
.IP W
Lambert W function. Only available if using the stand-alone maths library,
described in the section ``STAND-ALONE MATHS LIBRARY'' below, or if using
the GSL EXTENSIONS. In addition,
one must explicitly choose it with \fB-EW\fR.
.RE
.IP
You can specify the operators in ``long form'' by preceding the list with a
colon (:) and separating them with whitespace. This gives you access to
other operators (whose single-characters symbols are not so mnemonic) when
using the GSL extension.
Be sure to quote the
parameter so the shell does not split the option apart. See also below
regarding LONG-FORM EXPRESSIONS and GSL EXTENSIONS.
.IP
There are lots of potential uses for \fB-N\fR. For example,
if you invoke \fBries\fR on a small irrational number,
you might get several solutions that involve
the unary and binary logarithm operators `ln' (natural logarithm) and `log_'
(log to base A of B). If you decide
you aren't interested in such solutions you can just
add \fB-NlL\fR to your command line, and all such solutions
will be skipped.
If you are checking an unknown number that you found in the context of
some larger problem, you probably have some idea what
constants and operators may be involved, or not involved,
in the phenomenon that produced your number. Use \fB-N\fR to
rule out functions you don't think are relevant.
Note that \fBries\fR will often run considerably slower when you limit
it to a very small set of symbols, mainly because it cannot
use its optimization rules (described below under
ALGORITHM). Also, with fewer symbols the average length of
expressions is longer, and that makes the search slower.
.IP \fB-S\fIsss\fR
permitted Symbol Set: Specifies a symbol set, as with \fB-N\fR, but has the
opposite effect: \fIonly\fR these symbols will be used. A \fB-S\fR also
cancels any \fB-E\fR, \fB-N\fR or \fB-O\fR options that were given;
meaning that if you wish to combine these options, the \fB-S\fR
should come first.
\fB-S\fR can be used to solve those old problems of the
sort ``How can the number 27 be expressed using only the
four basic operators and the digit 4?'' The answer is
given by:
\FCries \(aq-S4+-*/\(aq 27 -Ox\FT
(The \fB-Ox\fR option is described next).
To solve the same problem using the \fB-N\fR
option, you'd have to type:
\FCries -Npef12356789rsqlL^v 27 -Ox\FT
If you give the \fB-S\fR option with no symbols, \fBries\fR will
display a table of all available symbols (as modified by any \fB-E\fR,
\fB-N\fR, \fB-O\fR and \fB-S\fR options) with their definition and
weights. This lone \fB-S\fR can be given along with a normal
\fB-S\fR option, but in any case \fBries\fR will exit after showing
the table.
.IP \fB-E\fIsss\fR
Enable: Enables (or re-enables) the use of symbols that may have been
disabled by an earlier \fB-S\fR or \fB-N\fR option. This is mainly
intended for use in combination with the \fB--include\fR option. If
one include file disables some symbols, this option can be used to
re-enable some or all of them. It is also required for use of the
Lambert W function (if using the the stand-alone math library) or
the GSL extension operators (see below on GSL EXTENSIONS), which are disabled
by default. A bare \fB-E\fR option with no symbols following enables
.I all
possible symbols.
.IP \fB-O\fIsss\fR
Only One: Specifies symbols which should appear no more than once
on \fIeach side\fR of the equation. This option can be combined with \fB-E\fR
or \fB-N\fR, in which case they augment each other.
If used with \fB-S\fR with the same symbol, the latter option
takes effect.
One additional symbol is available with \fB-O\fR:
.RS 1.2i
.IP x
The variable on the left-hand-side
.RE
.IP
Thus, you can use \fB-Ox\fR to limit \fBries\fR's output to equations
that have only one `\fIx\fR' in them and are therefore easy to
solve for \fIx\fR using only the most basic algebra techniques.
This also makes \fBries\fR's output more like that of
traditional expression-finders, which search for
expressions equal to \fIx\fR rather than equations in \fIx\fR. Here's an
example: \FCries -i 16\FT gives the answer
``\fIx\fR^2 - \fIx\fR = 3^5'' with \fIx\fR very close to 16,
because 16^2-16 is close to 3^5. \FCries -i 16 -Ox\FT replaces
that answer with ``5 \fIx\fR^2 = 6^4''.
.IP \fB--S-RHS\ \fIsss\fR
.IP \fB--N-RHS\ \fIsss\fR
.IP \fB--E-RHS\ \fIsss\fR
.IP \fB--O-RHS\ \fIsss\fR
These options work just like the
\fB-S\fR, \fB-N\fR, \fB-E\fR, and \fB-O\fR
options listed above, except that they apply
.I only
to the RHS of the equation, or more precisely, only to expressions that do
not contain \fCx\fR, the ``variable'' representing the number being solved
for.
There are no corresponding LHS-only setters: setting different values for
LHS and RHS involves setting the ``normal'' value with
.BR -O / -N / -E / -S
and then setting the RHS value to override it on the right-hand side.
.IP
These RHS-only settings are
.I ignored
when ``sorta-solving'' equations to move the variable over to one side (see
the \fB-s\fR option), and when doing canonical reduction (see the
\fB--canon-reduction\fR option). Only the restrictions and permissions
applied by the regular
.BR -O / -N / -E / -S
options apply.
.SH Options Limiting the Type of Solutions
Several options are used to choose what types of expression can be
used in the equations that are presented as solutions.
.IP \fB-i\fR
Integer: Require that all expressions, and all subexpressions, must
have integer values. This is primarily useful if you are searching for
an exact solution for a large integer. Note that inexact solutions
will still be given, but both sides of the equation will be integers.
An example of this is ``2 \fIx\fR = 7^3'' where \fIx\fR=173.
\fB-i\fR is interpreted as \fB-r\fR (described below) if the supplied
target value is not an integer.
.IP \fB-ie\fR
Integer, Exact. Like \fB-i\fR, but exits after reporting an exact
match (if found). This equivalent to \fB-i\fR combined with
\fB--min-match-distance 0\fR. To not report any inexact matches at
all, use \fB--max-match-distance 0\fR (described in more detail
below).
.IP \fB-r\fR
Rational: Require that all equations have a single \fIx\fR and that
all subexpressions not involving \fIx\fR are rational (an exact ratio
of two integers). This is primarily useful if you are searching for
rational approximations. This option is essentially just shorthand for
using the \fB-N\fR and \fB-E\fR options to allow only addition,
subtraction, multiplication and division, excluding irrational
constants and transcendental functions, etc.
.IP \fB-re\fR
Rational, ``Exact''. Like \fB-r\fR, but exits after reporting an
``exact'' match (if found). This equivalent to \fB-r\fR combined with
\fB--min-match-distance 0\fR.
Note that computers are (famously) unable to make exact
calculations with fractions as simple as 1/3. To exit on a match
within some ``epsilon'', use \fB--max-match-distance\fR with a nonzero
epsilon; to reject inexact matches use \fB--max-match-distance\fR
(these options are described in detail below).
.IP \fB-c\fR
Constructible: Require that all equations have a single \fIx\fR and
that all subexpressions are ``constructible'' in the sense of
Euclid's \fIElements\fR, given a unit interval. This is
like the \fB-r\fR option except that squares, square roots and the
golden ratio \fIphi\fR are also allowed. All results will be easily
solvable for \fIx\fR and will use only addition, subtraction,
multiplication, division, and square roots.
If you add the option \fB-Ex\fR, more than one \fIx\fR may appear
in the solution. This gives answers that, when solved for \fIx\fR, are
not constructible from the unit interval, but both sides of the
(unsolved) equation \fIare\fR constructible given \fIx\fR and a unit
interval. For example \FCries 1.3263524026321 -c -Ex\FT finds the
solution ``\fIx\fR \fIx\fR^2 = 7/3''; \fIx\fR is the cube root of
7/3 which is not itself constructible. \fBries\fR's answer reflects
the fact that 7/3 can be constructed from its cube root (although the
opposite construction is impossible).
.IP \fB-a\fR
Algebraic: Generate equations whose roots are ``algebraic numbers''.
This is similar to the \fB-c\fR option, but also allows \fIn\fR^th
powers and roots. The trigonometric functions (sine, cosine, and
tangent) are allowed but their arguments will always be rational
multiples of \[*p]. More than one \fIx\fR is allowed (unless you
follow \fB-a\fR with the option \fB-Ox\fR) so the equations might not
be easy to solve.
.IP \fB-Ox\fR
Using the \fB-O\fR option (described above) with the symbol `x' tells
\fBries\fR to limit its search to solutions that can be expressed in
``closed form'' using the basic constants, elementary and
transcendental functions. This concept of ``closed-form number'' is
described by Timothy Chow in his 1998 paper \fIWhat is a closed-form
number?\fR.
.IP \fB-l\fR
Liouvillian: Generate equations whose roots are ``EL numbers''
(exponential-logarithmic), as described by Timothy Chow in his 1998
paper \fIWhat is a closed-form number?\fR.
.SH Options Affecting Output Format
.IP \fB-s\fR
Sorta Solve, by Shifting to right-hand side: With this option,
\fBries\fR will display equations with just a single ``\fIx\fR'' on
the left-hand side of the equal sign. It isn't ``solving'' the
equations, but merely performing algebraic transformations to move
everything except one \fIx\fR to the right-hand side:
``\fIx\fR(\fIx\fR+1) = 7'' becomes ``\fIx\fR = 7/(\fIx\fR+1)''. You
can combine this option with \fB-Ox\fR to eliminate this issue, but
with that option \fBries\fR will no longer find solutions that require
more than one ``\fIx\fR'', like ``\fIx\fR^\fIx\fR = 2'' for 1.55961.
.IP \fB-x\fR
X Values: Print actual values of \fIx\fR (the roots of the equations
found) rather than expressing \fIx\fR as \fIT\fR plus/minus a small
number, where \fIT\fR is your target number.
``\fB--absolute-roots\fR'' is a synonym for \fB-x\fR.
.IP \fB-F\fIn\fR
Format: Controls the way expressions are formatted in the main output.
If \fIn\fR is omitted it is 3 (``-F'' for ``FORTH Format''); if
\fB-F\fR is not specified at all, the format will be 2. The following
formats are available; each shows the output of \FCries 1.506591651
-F\FT\fIn\fR:
Format 0: Compressed FORTH-like postfix format: Each operator and
constant is just a single symbol. The symbols are as listed above under
the \fB-N\fR option.
.fam C
.ps -2
x1- = 2r for x = T - 0.00659165 {50}
xlr = 6q for x = T - 0.00241106 {62}
x4^ = p2+ for x = T - 0.000766951 {68}
x1+s = p2* for x = T + 3.66236e-05 {69}
.ps +2
.fam T
Format 1: Infix format, but with single-letter symbols. If this format
is specified, a table of symbols will be printed after the main table
of results. The rest of the expression syntax is the same as the normal
format. For example, ``q(l(\fIx\fR)) = p-1'' means ``sqrt(ln(\fIx\fR))
= pi - 1''.
.fam C
.ps -2
x-1 = 1/2 for x = T - 0.00659165 {50}
1/l(x) = q(6) for x = T - 0.00241106 {62}
x^4 = 2+p for x = T - 0.000766951 {68}
(x+1)^2 = 2.p for x = T + 3.66236e-05 {69}
.ps +2
.fam T
Format 2: Standard infix expression format (this is the default).
.fam C
.ps -2
x-1 = 1/2 for x = T - 0.00659165 {50}
1/ln(x) = sqrt(6) for x = T - 0.00241106 {62}
x^4 = 2+pi for x = T - 0.000766951 {68}
(x+1)^2 = 2 pi for x = T + 3.66236e-05 {69}
.ps +2
.fam T
Format 3: Print solutions in postfix format, similar to that used
in FORTH and on certain old pocket calculators. This is close to the
format used internally by \fBries\fR (to get the exact, condensed format,
use \fI-F0\fR). This is intended mainly for
use by scripts that use \fBries\fR as an engine to generate
equations and then perform further manipulation on them. However,
this option will also help you distinguish
what symbols were actually used internally to generate an answer.
For example, `squared' and `to the power of 2' both show up as `^2' in
the normal output, but in postfix they appear as ``dup*'' and ``2 **''
respectively.
.fam C
.ps -2
x 1 - = 2 recip for x = T - 0.00659165 {50}
x ln recip = 6 sqrt for x = T - 0.00241106 {62}
x 4 ** = pi 2 + for x = T - 0.000766951 {68}
x 1 + dup* = pi 2 * for x = T + 3.66236e-05 {69}
.ps +2
.fam T
Most of the symbols used by \fB-F3\fR are self-explanatory. The
nonobvious ones are:
\fBneg\fR for negate,
\fBrecip\fR for reciprocal,
\fBdup*\fR for square,
\fBsqrt\fR for square root,
\fB**\fR for power (A^B),
\fBroot\fR for Bth root of A,
\fBlogn\fR for logarithm (to base B) of A.
For these last three, \fIA\fR is the first
operand pushed on the stack and \fIB\fR is the second.
The setting of \fB-F\fR does not affect expressions displayed by the
various \fB-D\fR diagnostic options (most of these use \fB-F0\fR,
and \fB-Ds\fR (``show your work'') uses \fB-F2\fR).
You may use the \fB--symbol-names\fR option (described below)
to redefine the appearance of formats 2 and 3.
.IP \fB-D\fIxx\fR
Display Diagnostic/Debugging Data: A detailed understanding of the
\fBries\fR algorithms (described below) is assumed. \fB-D\fR is
followed by one or more letters specifying the messages you want to
see. Options \fBA\fR through \fBL\fR and \fBa\fR through \fBl\fR
(except \fBE\fR and \fBe\fR) apply to the LHS and RHS respectively.
For each option, the number of lines of output that you can expect
from a command like \FCries -l2 2.5063141592653589 -D\FT\fIx\fR (with
\fIx\fR replaced by a single letter) is shown:
.RS 0.7i
.IP A,a
\fB[42836; 87770]\fR show partial expressions that are ``pruned'' (ignored) because of arithmetic error (e.g. divide by zero)
.IP B,b
\fB[3173; 2714]\fR show partial expressions pruned for being zero, or derivative nearly zero; or outside range given by \fB--min-equate-value\fR and \fB--max-equate-value\fR
.IP C,c
\fB[81056; 697227]\fR show partial expressions pruned for being non-integer (and -i option was given); or irrational (and -r option given); etc. (sample command is \FCries -l2 1047 -i -DC\FT )
.IP D,d
\fB[1751; 4350]\fR show partial expressions pruned because of overflow
.IP E,e
\fB[102356; 272746]\fR show expressions pruned because their value matches one already in database
.IP F,f
\fB[349368; 848882]\fR show \fB--canon-reduction\fR operations on expressions before adding to database (sample command is \FCries -l2 2.50631415926 --canon-reduction nr25 -DF\FT )
.IP G,g
\fB[96112; 97337]\fR show expressions added to database
.IP H,h
\fB[409175; 816240]\fR show attributes of each partial expression tested
.IP I,i
\fB[3904331; 7759741]\fR show each new symbol to be added before complexity pruning
.IP J,j
\fB[2579116; 5102516]\fR show symbols skipped by complexity pruning
.IP K,k
\fB[257302; 558199]\fR show symbols skipped by redundancy and tautology rules
.IP L,l
\fB[61994; 114453]\fR show symbols skipped to obey -O option (sample command is \FCries -l2 2.50631415926 \(aq-O-+/^v*qsrlLeEpf\(aq -DL\FT )
.IP m
\fB[10247603]\fR show all metastack operations
.IP M
\fB[46]\fR show memory allocation benchmarks, and enable automatic exit when memory gets slow (see \fB--memory-abort-threshold\fR option)
.IP n
\fB[136]\fR show Newton iteration values and errors if any
.IP N
\fB[461]\fR show work in detail: operator/symbol, x and dx at each step
.IP o
\fB[539235]\fR show match checks
.IP p
\fB[112]\fR show preprocessing transformations prior to conversion to infix
.IP Q
\fB[51]\fR show manipulations to remove \fB--canon-reduction\fR from equations before root-finding
.IP q
\fB[140]\fR show close matches dispatched to Newton and results of test
.IP r
\fB[1806085]\fR show results (value and derivative of operands and result) for each opcode executed
.IP S
\fB[100]\fR show solve-for-x work: displays all operations performed by the \fB--try-solve-for-x\fR option to transform an equation into ``solved'' form
.IP s
\fB[277]\fR show your work: displays values of each subexpression for every reported answer. Subexpressions are shown in normal (infix) syntax, which is useful in combination with \fB-F0\fR to see the postfix format used with options like \fB--eval-expression\fR
.IP t
\fB[11017]\fR show all abc-forms passed to expression generation
.IP u
\fB[48895]\fR show steps of min/max complexity ranging for each abc-form
.IP v
\fB[5525]\fR show number of expressions generated by each abc-form
.IP w
\fB[32922]\fR show details of abc-form generation (pruning, weights, etc.)
.IP x
\fB[91]\fR show all rules used (varies with the \fB-N\fR, \fB-O\fR, and \fB-S\fR options)
.IP y
\fB[736]\fR statistics and decisions made in main loop
.IP z
\fB[55]\fR initialization and other uncategorized messages
.IP 0
\fB[1712490]\fR list the entire expression database after every pass
through the main loop
.RE
.IP
Of these, \fB-Ds\fR is probably the most useful and fun to look at.
\fB-Dy\fR gives a nice top-level view of the statistics of the search.
Most of the options that generate lots of output are useful if
filtered through \FCgrep\FT; this can tell you why a certain
subexpression is or is not appearing in results. \fB-DG\fR and
\fB-Dg\fR can be useful if you want to use \fBries\fR to generate a
massive list of expressions for processing by another program; for
this reason its output uses infix notation. Most other \fB-D\fR
options print subexpressions in the \fB-F0\fR terse postfix format.
.SH EXTENDED OPTIONS
Longer names are used for options that are thought to be less commonly
wanted, or are more likely to be used only within \fB--include\fR files.
.IP \fB--include\fR\ \fIfilename\fR
.IP \fB-p\fIfilename\fR
.IP \fB-p\fR
Load one or more options from file \fIfilename\fR. The options
``\fB--include\fR \fIfilename\fR'' and ``\fB-p\fIfilename\fR'' are
equivalent; note that one requires a space before \fIfilename\fR and
the other cannot have a space (\fB-p\fR alone has a related function,
described below). \fBries\fR will attempt to open the named file
(which may be a simple filename or a path), or the given name with
``\FC.ries\FT'' appended. If either is found, \fBries\fR will scan it
for parameters and arguments separated by whitespace. Any control
characters count as whitespace. Any `#' character that comes at the
beginning of a line or immediately after blank space denotes a comment
and the rest of the line will be ignored. For example, if there is a
file ``\FChst.ries\FT'' containing the following:
.fam C
.ps -2
# hst.ries: High School Trigonometry settings
--trig-argument-scale 1.74532925199433e-2 # pi/180
-NLleEv # No log, ln, e, e^x or arbitrary roots
-Ox # Only allow one \(aqx\(aq on the left-hand-side
-x # Show equation roots as "x = 123.456"
# rather than "x = T + 1.23e-4"
.ps +2
.fam T
then giving the option ``\fB-phst\fR'' is equivalent to giving the
options ``\fB--trig-argument-scale 1.74532925199433e-2 -NLleEv -Ox -x\fR'',
in that order.
A parameter file may additionally invoke another parameter file
with the \fB--include\fR option. When it encounters this option,
\fBries\fR will apply the options in the included file, then continue
with the rest of the first file. These may be nested up to 25 levels
deep. If a file includes itself recursively (either directly or
indirectly) \fBries\fR will exit with an error.
It is an error for \fB--include\fR or the end of an included file
to come between an option and its arguments. For example, ``\FCries
1.2345 --eval-expression --include expressions.txt\FT'' will produce
an error regardless of the contents of ``\FCexpressions.txt\FT'',
because \fB--eval-expression\fR must be followed immediately by its
argument(s). On the other hand, if ``\FCexpressions.txt\FT'' contains
the \fB--eval-expression\fR option, like so:
.fam C
.ps -2
# expressions.txt: Useful functions of one argument
--eval-expression
xsr # 1/(x^2)
1xq-r # 1/(1-sqrt(x))
2xl1+^ # 2^(ln(x)+1)
.ps +2
.fam T
then the command ``\FCries 1.2345 --include expressions.txt\FT''
works, and shows the values of the three expressions where \fIx\fR is
1.2345.
If you have a file called ``\FC.ries_profile\FT'' or
``\FCries_profile.txt\FT'' in your home directory, \fBries\fR will
load it as if you specified it with a \fB--include\fR at the very
beginning of the parameters. If you have such a file and wish to
prevent it from being used, give a bare \fB-p\fR (without a filename)
at the very beginning of your \fBries\fR options. If you wish to give
some parameters and have \FC.ries_profile\FT loaded \fIafter\fR your
parameters, include \fB-p\fR again at the point where you want
\fBries\fR to use the profile. For example, if your
\FC.ries_profile\FT contains ``\fB--trig-argument-scale 1\fR'' and you
have a \FChst.ries\FT with contents as shown above, then giving the
optiions ``\fB-phst\fR \fB-p\fR'' will use all of the settings in
\FChst.ries\FT except the \fB--trig-argument-scale\fR.
Two more example profiles are the ``Latin'' and ``Mathematica''
settings files linked from the top of the main RIES webpage.
.IP \fB--absolute-roots\fR
This is a synonym for the \fB-x\fR option, described above.
.IP \fB--algebraic-subexpressions\fR
This is a synonym for the \fB-a\fR option, described above.
.IP \fB--any-exponents\fR
This option cancels any restrictions on subexpressions used as an
exponent, such as those set by the \fB--algebraic-subexpressions\fR
and \fB--liouvillian-subexpressions\fR options.
.IP \fB--any-subexpressions\fR
This option cancels any restrictions on subexpressions, as imposed by
options such as \fB--algebraic-subexpressions\fR. This might be useful
if you are using one of the class selectors like \fB-a\fR or \fB-c\fR
as shorthand for all the restrictions of that particular class, and
then re-enable a function like \fIe\fR^\fIx\fR using \fB-EE\fR.
.IP \fB--any-trig-args\fR
This option cancels any restrictions on subexpressions used as an
argument to a trigonometric function, such as those set by
the \fB--algebraic-subexpressions\fR and
\fB--liouvillian-subexpressions\fR options.
.IP \fB--canon-reduction\fR\ \fIsymbols\fR
Apply simple transformations in an effort to make all expression
values fall in the range [1 ... 2). This option improves the
efficiency of the \fBries\fR algorithm (described in the ``ALGORITHM''
section below) by increasing the chances of two expressions forming a
match. This allows it to use less memory and time to achieve any given
amount of precision.
This option should be followed by one or more symbols which
represent the operations \fBries\fR will try to apply to expressions:
.RS 0.7i
.IP n
Negate expressions when possible to make all values positive.
.IP r
Take the reciprocal when possible to make all expressions fall outside
the range (-1 ... 1).
.IP 2
Multiply by 2 when possible to increase the magnitude of
expressions in the range (-1 ... 1).
.IP 5
Divide by 2 (i.e. multiply by 0.5) when possible to decrease the
magnitude of expressions that fall outside the range (-2 ... 2).
.RE
.IP
In these descriptions, the words \fIwhen possible\fR refer to the fact
that \fB--canon-reduction\fR will respect any limits imposed by the
symbolset options \fB-N\fR, \fB-O\fR and \fB-S\fR. So if you use the
option \fB-On\fR together with \fB--canon-reduction n\fR, the negation
operator will still be used only once per expression.
Although it makes \fBries\fR more efficient, this option also
causes the printed results to have greater complexity scores, and
complexity scores will increase somewhat more erratically. \fBries\fR
will try to simplify its printed results by undoing
\fB--canon-reduction\fR transformations on both sides of the equal
sign. For example, \FCries 2.50618 --canon-reduction nr25\FT might
yield the result ``\fIx\fR^\fIx\fR/2 = (1+9)/2'', which simplifies
to ``\fIx\fR^\fIx\fR = 1+9''. But when only one side has a ``/2'',
\fBries\fR cannot fix it, so the same example gives an overly complex
``1/(\[*p]-\fIx\fR) = \[*p]/2''.
.IP \fB--canon-simplify\fR
When reporting a match, remove common factors or terms from both sides
of the equation. This is the default.
.IP \fB--constructible-subexpressions\fR
This is a synonym for the \fB-c\fR option, described above.
.IP \fB--define\fR\ \fIweight\fB:\fIname\fB:\fIdescription\
\fB:\fR[\fB:\fR]\fIformula\fR
.
Define a custom operation. You can define your own operations as postfix
expressions over the existing set of operations. The argument must begin
with a positive integer weight (see \fB--symbol-weights\fR), followed by
the short name of the operation (which will be shown in the equations when
it is used), a description of the operation (shown at the bottom of the
output), and lastly the formula for the operation, all separated by
colons.
The formula can be given in either of two forms: ``short'' form or
``long'' form. The short form is the FORTH-like postfix syntax that is
displayed when you use the \fB-F0\fR option, described above. There are
two additional operations available which you might find useful:
.TS
center;
cb ci l .
| dup duplicate the top element on the stack
@ swap swap the top two elements on the stack
.TE
.RE
.IP
So you could define a function \fIXeX(x) = x \fRexp(\fIx\fR) (the inverse of
the Lambert W function) with
.IP
\fC--define \(aq4:XeX:XeX(x) = x*exp(x):|E*\(aq\fR
.IP
Or the hyperbolic sin function (sinh) with
.IP
\ \ \ \fC--define \(aq4:sinh:sinh(x) = hyperbolic sine:E|r-2/\(aq\fR
.IP
Or the hypotenuse function
.ie t \{\
.EQ
( sqrt { a sup 2 + b sup 2 } )
.EN
.\}
.el sqrt(a^2+b^2)
with
.IP
\ \ \ \fC--define \(aq4:hypot:hypot(a, b) = sqrt(a^2+b^2):s@s+q\(aq\fR
.IP
Note that you will have to take care to quote your argument against
expansion by the shell (or breaking on spaces), as shown above. In a file
for use with \fB--include\fR you should enclose the argument with
double-quotes (\(dq).
The ``long form'' for an expression is the same as what you
would see if you used the ``\fB-F3\fR'' option. Signal a long-form
expression by adding an extra colon at the beginning. Note that in
long-form expressions, you
.I must
separate all operators with spaces. So the above expressions in long-form
would look like this:
.RS 0.2i
.IP
.nf
.fam C
.ps -1
--define \(aq4:XeX:XeX(x) = x*exp(x)::dup exp *\(aq
--define \(aq4:sinh:sinh(x) = hyperbolic sine::exp dup recip - 2 /\(aq
--define \(aq4:hypot:hypot(a,b)=sqrt(a^2+b^2)::dup* swap dup* + sqrt\(aq
.ps
.fam
.fi
.RE
.IP
One advantage to using the long form is that you can define functions in
terms of other functions already defined. So you can get all three
hyperbolic trigonometric functions like this:
.RS 0.2i
.IP
.nf
.fam C
.ps -1
--define \(aq4:sinh:sinh = hyperbolic sine:E|r-2/\(aq
--define \(aq4:cosh:cosh = hyperbolic cosine:E|r+2/\(aq
--define \(aq4:tanh:tanh = hyperbolic tangent::dup sinh swap cosh /\(aq
.ps
.fam
.fi
.ft
.RE
.IP
A
.B funcs.ries
file containing some definitions is included with the \fBries\fR source.
.IP
Note that operators used inside definitions are not affected by being
disabled or restricted by the
.BR -N ", " -O ", or " -S
operators, although the defined operator may be. That is, if you have
defined the hyperbolic trigonometric functions as above, you can still
forbid the use of the exponentiation operator with
.B -NE
without restricting the use of your user-defined
.BR sinh / cosh / tanh
functions, even though they are defined in terms of it. The user-defined
functions can be restricted on their own, though, so
.B -N:cosh
will forbid the \fBcosh\fR function.
.IP \fB--constant\fR\ \fIweight\fB:\fIname\fB:\fIdescription\fB:\fIvalue\fR
.IP \fB-X\fR\ \fIweight\fB:\fIname\fB:\fIdescription\fB:\fIvalue\fR
Define a new constant that \fBries\fR can use in its calculations. So for
example you might want to allow the Euler-Mascheroni constant \[*g]\/ to
be an allowed constant. You can do so with
.RS 0.2i
.IP
.fam C
.ps -2
.nf
-X \(aq4:EulerGamma:Euler-Mascheroni Constant:0.57721566490153286060651209008\(aq
.ps
.fam
.fi
.RE
.IP
A
.B constants.ries
file containing some sample constants is included with the \fBries\fR
source code.
.IP \fB--derivative-margin\fR\ \fIvalue\fR
Specify the limit to how small the derivative of any expression or
subexpression containing \fIx\fR can be in relation to the
expression's value. By default this is 10^-6, so that an expression
containing \fIx\fR is rejected if its value is more than a million
times its derivative. For really large target values, this doesn't
work because the expression ``\fIx\fR'' (with a derivative of 1.0)
would be rejected. So if the magnitude of your target is larger than
10^5, \fBries\fR will set this limit correspondingly lower. For
example, if your target value is 10^8, \fBries\fR automatically sets
a \fB--derivative-margin\fR value of 10^-9.
If you do not consider these defaults suitable, use this option
to pick your own value. For example in the command \FCries 12345
--derivative-margin 8e-5\FT, derivatives of expressions can be as
small as 8x10^-5 times the expression's value. In calculating any
possible answers, \fBries\fR would allow ``\fIx\fR^2'' because the
ratio between d/d\fIx\fR \fIx\fR^2 and \fIx\fR^2 is about 1.62e-4,
which is big enough to surpass the margin. However, any answers
involving ``sqrt(\fIx\fR)'' would be rejected because the ratio between
d/d\fIx\fR sqrt(\fIx\fR) and sqrt(\fIx\fR) is only 4.05e-5:
.ta 1.2iC 2.2iC 3.4iC 4.4iC
expression value d/d\fIx\fR(expr.) ratio
.br
\fIx\fR^2 152399025 24690 1.62e-4
.br
\fIx\fR 12345 1.0 8.1e-5
.br
sqrt(\fIx\fR) 111.108 0.0045 4.05e-5
Indeed, the results of \FCries 12345\FT include the equation
``2(sqrt(\fIx\fR)-9) = (2 e)^pi'', but with the option
\fB--derivative-margin 8e-5\fR that answer is left out.
.IP \fB--explicit-multiply\fR
Always use the ``*'' symbol when displaying results, rather than the
default behavior of omitting ``*'' when multiplicaton can be implied
by writing the multiplicands next to each other. This is useful if you
need to copy \fBries\fR output into a calculator, computer program or
spreadsheet formula.
.IP \fB--integer-subexpressions\fR
This is a synonym for the \fB-i\fR option, described above.
.IP \fB--match-all-digits\fR
.IP \fB--mad\fR
Request that all reported matches should match all of the supplied
digits. This is equivalent to adding a `5' to the end of your target
value, along with a \fB--max-match-distance\fR value equal to the
magnitude of this appended `5' digit. It also selects the \fB--x\fR
option, unless the \fB--wide\fR option is also given.
For example, the command \FCries 2.5063 --mad\FT is equivalent to
\FCries 2.50635 --max-match-distance 0.00005 -x\FT, and the first
reported match is \fIx\fR^2+e = 9, which is true for \fIx\fR =
2.506335... Without \fB--mad\fR it reports 2 \fIx\fR = 5 and a few
other answers that do not match all of the digits in 2.5063.
.IP \fB--max-equate-value\fR\ \fIvalue\fR
.IP \fB--min-equate-value\fR\ \fIvalue\fR
Specify the maximum and minimum values for the LHS and RHS of any
reported equations. For example, the command \FCries 2.50618\FT would
normally give ``2 \fIx\fR = 5'' as the first solution; both sides of
that equation are about 5. But the command \FCries 2.50618
--max-equate-value 3\FT instead gives ``\fIx\fR-2 = 1/2'' as the first
answer: this is an equivalent solution, but expressed as an equation
in which both sides of the equal sign are less than 3. Similarly,
\FCries 2.50618 --min-equate-value 27\FT gives the answer
``(\fIe\fR^\fIx\fR)^2 = \fIe\fR^5''.
.IP \fB--max-match-distance\fR\ \fIvalue\fR
Specify the maximum distance between your given target value \fIT\fR
and the roots \fIx\fR of any reported equations. This sets a minimum
level of accuracy, overriding the default, which is 1% of the
size of your target value. For example, the command \FCries 2.5063\FT
will use a threshold that is 1% of 2.5063, or about 0.025. It
gives as its first answer the equation 2\fIx\fR = 5, an equation whose
root (solution) is 2.5. This differs from the target value 2.5063 by
0.0063. If you specify an initial threshold of 0.001 with the command
\FCries 2.5063 --max-match-distance 0.001\FT, then 2\fIx\fR = 5
is not reported because 0.0063 is bigger than your threshold 0.001;
instead the first match will be ``\fIx\fR^2 = 2 \[*p]''
(which comes within about 0.0003 of the target 2.5063).
Use a zero argument to specify that \fBries\fR should only report
an ``exact'' match, if any (and note that this ``exact'' match might
be more complex than the obvious answer, because of roundoff errors;
see UNEXPECTED BEHAVIOR and BUGS below). Note that this is different
from \fB--min-match-distance 0\fR, which prints inexact matches and
stops after the ``exact'' match.
Use a negative argument to specify a match threshold in
proportion to your target value. For example, \FC--max-match-distance
-0.001\FT specifies that the first match must be within 1 part in
1000 (or 1/10 of one percent) of the magnitude of the target.
If your choice of \fB--max-match-distance\fR is so stringent that
the first match takes longer than 2 seconds, \fBries\fR will display
progress messages until a match is found. Use the \fB--no-slow-messages\fR
option to suppress these.
There is also a \fB--min-match-distance\fR option (described
below), which serves an entirely different purpose.
.IP \fB--max-matches\fR\ \fIN\fR
.IP \fB-n\fIN\fR
Limit the number of reported matches to a positive integer \fIN\fR.
This is particularly useful with certain options (such as
\fB--no-refinement\fR) that generate a lot of matches. The default
\fIN\fR is 100.
.IP \fB--max-memory\fR\ \fIsize\fR
This option tells \fBries\fR not to use more than the given amount of
memory (size specified in bytes). This is particularly useful in
combination with a