Consider this problem to be solved, which is purely for illustration of the input format.
This problem has four equations in three unknowns:
.5 * x1 + .4 * x2 + .3 * x3 = 1., estimated error = 0.01
.2 * x1 + .4 * x2 + .5 * x3 = .5, estimated error = 0.01
.5 * x1 + .1 * x2 + .5 * x3 = .2, estimated error = 0.01
.6 * x1 + .1 * x2 + .6 * x3 = .2, estimated error = 0.01
The problem.csv input file for this problem might then look like this:
=, .5, .4, .3, 1, .01
=, .2, .4, .5, .5, .01
=, .5, .1, .5, .2, .01
=, .6, .1, .6, .2, .01
Every solver expects the input to be in a file named problem.csv.
But each solver writes its output to a slightly different name, such as solveS.csv.
The first line of the problem.csv file must have two values:
1. The total number of equations and constraints, or rows, in the problem (4 here).
2. The number of variables, or columns, in the problem (3 here)
The four lines beginning with”=” are the ordinary least-squares equations:
· each begins (after the “=”) with the three variable coefficients.
· then the right-hand-side value follows
· then the estimated error in the right-hand-side value follows. The estimated error (or standard deviation estimate) in each right hand side element here is 0.01. Please write in all the error estimates you know, and put zero for any you really don’t know. Depending on the program you choose to use to solve the system, it may need error estimates for all these ordinary equations, or none at all.
With this problem.csv file you can apply any of the solvers just by downloading them
to your Windows Desktop (or other chosen folder) and double-clicking on the file name.
The problem.csv file and the solver must be in the same folder.
The resulting output file will be in the same folder, such as your Desktop.
Now, suppose you want to add constraints to say that the three unknowns must add to 3,
and that the first one must be non-negative. You could expand the equations as follows.
(Note: explanatory comments added at the right… it is OK to have such notes in the file.)
6, 3 <- 6 equations or constraints; 3 unknowns
=, .5, .4, .3, 1, .01, <- means .5X1 + .4X2 + .3X3 = 1 +/- 0.01
=, .2, .4, .5, .5, .01, <- means .2X1 + .4X2 + .5X3 = .5 +/- 0.01
=, .5, .1, .5, .2, .01, <- etc
=, .6, .1, .6, .2, .01, <- etc
!, 1, 1, 1, 3, <- the constraint that X1 + X2 + X3 == 3
>, 1, 0, 0, 0, <- the constraint that X1 >= 0
You can also use < to indicate that the equation must result in a non-positive value.
There are several more features for convenience:
SUM,3 means the sum of the unknowns must be 3, for example
END means to stop reading equations. This is to allow the count
of equations to be set to a large value and not have to change it
every time you add or delete an equation
NONNEG adds a non-negativity constraint for EVERY unknown.
This is a common need, so we have made it easy.
In the above example, three inequality constraints would result.
COLUMNS Or just COL, or C, means that the remaining fields on this
line are labels for the unknowns.
This is to help you read the solution file.
ROWLABELS or just ROWS, or R, means that each equation (but not constraints)
has an identifying name appended after the error estimate.
Again, this is to help in readability of the solution file.
So the system of equations/constraints might now look like this:
99, 3 <- max 99 equations or constraints;3 unknowns
#This is my first problem! <- a comment line
COLUMNS, X1, X2, X3 <- labels for the unknowns in the output file
ROWS <- means to use the equation names below
=, .5, .4, .3, 1, .01, Sodium <- means .5X1 + .4X2 + .3X3 = 1 +/- 0.01
=, .2, .4, .5, .5, .01, Calcium <- means .2X1 + .4X2 + .5X3 = .5 +/- 0.01
=, .5, .1, .5, .2, .01, Argon <- etc. This equation is for “Argon”
=, .6, .1, .6, .2, .01, Silica <- etc
SUM, 3 <- the constraint that X1 + X2 + X3 = 3
NONNEG <- to force X1, X2, and X3 non-negative
END <- to end the reading
Note: If you do not use the “END” feature to end reading, then
you must count the equations, including the SUM and NONNEG lines.
The COLUMN, ROW, END, and #comments do not count in the equation count.
So the equation count here would be 6 (4 obvious equations plus SUM and NONNEG).
This counted equation mode is mostly intended for computer-created input files.
Hand-written files would normally use the max number of equations mode.
Note: Our solvers are limited to 99 variables (that is, columns) and 99 regular equations.
Inequality constraints, equality constraints, and SUM and NONNEG are not limited.
They are also not allowed to have a label like ordinary equations.
(This is a limitation only of this input form. Rejtrix.h is not so limited.)
Note: '<' constraints will be converted to '>' constraints by the program.
They will show as '>' constraints in the output, with all the coefficients negated.
Note: Usually the ORDER of the equations is unimportant. But in some cases the order can have an effect on the solution process, especially in the case of equality constraints. If there are conflicting equality constraints (such as x1=0 and x1=9) then the earlier one will usually take precedence. Further, it sometime helps the solution process if the ordinary equations are ordered with decreasing right hand side values (after the rows are scaled however you need to scale them). In most cases these issues can be ignored.
Note: The COMMAS between the numbers are optional. There are shown here because we presume the
input will typically be prepared with Microsoft Excel or a similar spread-sheet program, and output’ed as comma-separated-value files, with the *.csv extension. If you are preparing them by hand in a text editor, or outputting them from a program then the use of the comma may be a nuisance and is not required.
But the output files from the solvers will use the *.csv format, for easy reading by Excel. Normally you should be able to just double-click on the solve*.csv file and have Excel open it.
Note: The solve*.csv files can also be read directly by any text file reader.
Because of this simple format, no graphs are inserted by the solvers.
It is assumed that the user can easily insert graphs in the file with Excel.
But you will need to save the file as a *.xls or *.xlsx or some other appropriate file
to save the graphs with the data.
· The above example (or very similar) is available as example3.csv.
· A slightly ill-conditioned realistic 6-variable system of equations is example6.csv.
· A quite ill-conditioned Hilbert matrix problem with 10 variables is example10.csv.
· The smallest possible ill-conditioned problem is available as example2.csv.
Remember that you can view these by opening them with a text editor like Wordpad, or with a spreadsheet program like Excel.