#ABOUT
SPNBOX implements the Petri net supervisory control functions originally developed 
for Matlab by Dr. Marian V. Iordache.

The functions were converted to C for use with the ACTS tool by Stephen Camp.

#COMPILING
To generate object files for the entire SPNBOX toolset, run "make" from the 
pntool/spnbox directory.

Note that SPNBOX makes use of the LPSOLVE MILP solver API found in the 
pntool/third-party directory. The makefile will attempt to copy the compiled 
library liblpsolve55.a from the LPSOLVE directories into the pntool/spnbox 
directory if it is not already present. If the LPSOLVE library is not present in
its own directory, the SPNBOX makefile will invoke LPSOLVE's linux-targeted 
makefile to build the lpsolve library.

#TESTING
The subdirectory "tests" contains test files for the SPNBOX functions. There are
source files for a test program for each function except chkcons, which is used
as a subroutine of other functions and so tested implicitly.
The makefile within the directory will make any of the test programs. To generate
the test program for a particular function, use a command of the form:
make <functionname>
This will generate an executable called <functionname>.exe.
Note that the makefile can be configured to include a set of debugging routines
from the third-party library memwatch that will aid in debugging memory errors.
See MEMORY DEBUGGING later in this file for more information. To include this
library, the "USEMEMWATCH" variable in the test makefile should be set to "yes".
If it is set to anything else the memory debugging routines will not be included.

make all will generate test executables for all spnbox functions.

To test the various functions in the matrixmath.c file, use make matrixmath. To 
test the functions in the extendedmatrix.c file, use make extendedmatrix.

For all with such test programs except that ipslv, the test program is implemented 
as a program that will read from an input stream containing text in a human-
readable format, interpret the text as parameters to the function, make a function
call, and display the results. For format specifications, see the comments in 
StructuredIO.c/h.

The programs may be invoked with a single command line argument, which will be 
taken as the name of a text file from which to read the input. If no command line
argument is used the test programs will take input from the console.

Pre-formatted test scripts with problems to test each part of a function have
been provided. These are named in the form test-<functionname>.txt. There is no
test script for admcon.c as the admcon function is thoroughly tested by its use
within the dp function.

Thus, to test ipsolve with the default test script the following command sequence
might be issued:

cd ~/pntool/spnbox/tests
make ipsolve
./ipsolve test-ipsolve.txt

#MEMORY DEBUGGING
The test makefile can compile and link the spnbox files so that their test 
routines will make use of the "memwatch" memory debugger. Memwatch is a set of 
routines, declared in memwatch.h in the pntool/third-party/memwatch-2.71/ 
directory, that overrides the standard memory allocation and deallocation 
functions with its own wrappers.

Memwatch keeps track of allocations and deallocations through its routines. It 
can detect some but not all array overwrites, underwrites, wild pointer writes, 
deallocations of invalid pointers, and various other potential errors related to 
dynamically allocated memory.

When a program that contains the Memwatch routines runs it will create a text 
file in the current directory, titled memwatch.log by default, that lists any 
errors or anomalies detected by the memwatch routines.

Note that the memwatch routines slow memory-related operations drastically.

See pntool/third-party/memwatch-2.71/USING for more information.
memwatch is licensed under the GNU public license, present in the file
pntool/third-party/memwatch-2.71/gpl.txt.

#FILES
Main directory:
- spnbox.h: This is the header file containing the definitions for all the SPNBOX
  functions, as well as various constant definitions.
- matrixmath.h & matrixmath.c: These implement various matrix arithmetic operations 
  used by other SPNBOX functions.
- extendedmatrix.h & extendedmatrix.c: These implement operations to insert or
  remove rows and columns from matrices. Note that these functions employ when
	possible optimizations that rely heavily on the internal details of matrix
	implementation, and so if the matrix implementation is ever changed these
	files will need to be modified accordingly.
- deallocation.c: This implements functions to deallocate the structures returned 
  by SPNBOX functions.
- Makefile: This is the main makefile. When used without a target it builds
  object files that implement all SPNBOX functionality.
	Use "make clean" to remove all object files, all library (*.a) files, and
	execute the clean command for the lpsolve library in the third-party/lp_solve_5.5
	directory.
	Use "make clean-partial" to remove all object files.
- Each of the other files corresponds to a single SPNBOX function.

tests subdirectory:
- test.c & test.h: These define and implement a few subroutines used by many of 
  the test programs as well as implemented the pntool "is_verbose" function to 
	ensure maximum verbosity during testing. The header file also includes header 
	files common to all the test programs.
- StructuredIO.c & StructuredIO.h: These define and implement a pair of functions,
  ParseStructure and DisplayStructure. ParseStructure is used used to parse human-
  readable text from a stream as described in a format string and with it fill
	an arbitrary number of variables. It is an analogue of sprintf with support
	for more complex data structures such as arrays and matrices.
	DisplayStructure is used to display such data structures in a human-readable
	format as described by a similar format string. For usage and format string
	information see the comments in the files. These functions are used by nearly
	all the test programs to make the collection of input easier.
- Makefile: This is the test makefile. It is responsible for building various
  test routines and takes targets as described above in #TESTING.
- All other files are the source files for the test executables for various
  functions or the test scripts intended to be used with various text executables.
