Ox utilities - Examples

info

Within long-lasting simulation or estimation programs, I tend to take up a call to this info routine. This only works if the number of iterations needed is known beforehand; then it is possible to calculate once in a while how long the computations are going to take. Otherwise, the program report just the number of iterations performed, and the time that it took.

Take the following example (more elaborate in exinfo.ox):

#include <oxstd.h>
#include <packages/oxutils/oxutils.h>
main()
{
  decl i, iN, mX;
  iN= 10000;
  info(0, iN);          // Initialize
  for (i= 0; i < iN; ++i)
    {
      if (imod(i, 1000)== 0)
        info(i, iN);
      mX= lengthycalculation();
    }
}

On the output, you'll see information like

-------------------------------------------------------------
   Number of elapsed iterations:       750
   Number of iterations to go:         250
   Elapsed time:                         7
   Time per 100 iterations:              0.93
   Estimate of remaining time:           2.33

indicating how long the estimation is expected to last.

infoinit

Optionally, if you want Ox to check for you if it is time to print timing information, you can use infoinit. Adapting the inner part of the program above to read

  infoinit(500, 1);
  for (i= 0; i < iN; ++i)
    { 
      info(i, iN);
      mX= lengthycalculation(iN);
    }

will print information every 500 iterations or every second, whichever comes first.

lockfile

This routine, together with its companion unlockfile can be used when you tend to run e.g. multiple instances of a simulation program, and don't want to be working on the same output file twice.

A call to

  ir= lockfile("thiscomputation");

checks for the existence of a file thiscomputation_lock.txt. If it does not exist, the routine creates it and returns true. If it already exists, apparently some other instance of Ox is working on thiscomputation, and false is returned. See the example exlock.ox for a basic implementation/usage.

PrintMatrix

This function basically works similar to the standard print function, but with LaTeX '&'s included. Also matrices with more than 6 columns can be printed, or with lines longer than 80 characters. For an example, see extable.ox below.

First, a matrix is filled with some `interesting' information to be printed. Then the column and row labels are filled in, just like an array with print formats for the elements in the matrix. Note how LaTeX commands can be used here, but a \ sign has to be escaped by including a double \\ instead.

The PrintMatrix command puts the matrix into the file with filehandle fh, or on the screen.

The first integer after the data matrix indicates the number of \hline commands that should be included before and after the table; the second controls the number of \hline's after the column labels.

#include <oxstd.h>
#include <packages/oxutils/oxutils.h>

main()
{
  decl i, aPrFmt, arLabs, acLabs, mX, nDim, mY, fh;

  nDim= 3;
  mX= rann(nDim, 1000);
  mY= meanr(mX)~varr(mX)~limits(mX')[:1][]';

  aPrFmt= acLabs= new array[nDim];
  for (i= 0; i < nDim; ++i)
    { aPrFmt[i]= "%7.3f";
      acLabs[i]= sprint("$R(", i, ")$"); }
  arLabs= {"$\\mu$", "$\\sigma^2$", "min", "max"};

  // Print the table to a file, with one line before and after the
  //   table, two lines between the column headings and the table
  //   itself, and with the LaTeX tabular environment included
  fh= fopen("table.out", "a");
  PrintMatrix(fh, "extable", aPrFmt, acLabs, arLabs, 
              mY', 1, 2, TRUE);
  fh= fclose(fh);

  // Print the table to screen
  PrintMatrix(0, "extable", aPrFmt, acLabs, arLabs, 
              mY', 1, 2, TRUE);
}

The result of the program looks like

\begin{tabular}{lrrr}
\hline
   extable & $R(0)$ & $R(1)$ & $R(2)$ \\
\hline\hline
     $\mu$ &   0.013 &  -0.025 &   0.003 \\
$\sigma^2$ &   0.974 &   0.954 &   0.990 \\
       min &  -3.372 &  -3.382 &  -2.988 \\
       max &   3.086 &   3.513 &   4.021 \\
\hline
\end{tabular}

printtex

The example extable.ox also uses a command printtex, which is supposed to be an even closer drop-in replacement for the Ox print command. A statement like

  printtex("%cf", {"%5.2f", "(%4.1f)"}, ranu(4,2));

results in

  &  0.78 & ( 0.1) \\
  &  0.96 & ( 0.9) \\
  &  0.93 & ( 0.3) \\
  &  0.12 & ( 0.7) \\

This routine also can take up row and column labels; the command fprinttex(fh, ...) can print the output to a specified file.

setseed

This routine I use to quickly change to a new random seed, based on the current time in hundreths of seconds (which gives a reasonably random result).

If I want a new seed, I use

  setseed(0)

but if I want a fixed seed, I change the line to

  setseed(1234)

which results in a call to ranseed() command.

TrackTime

Sometimes it is useful to profile a program, to know exactly in which routine a program spends most of its time. With such information, it may be worthwhile to put some effort in improving the efficiency of that routine.

For this purpose, finding where the gain can be made, I wrote these TrackTime routines. They are most easily explained using a small example program (available as extrack.ox):

#include <oxstd.h>
#include <packages/oxutils/oxutils.h>

main()
{
  decl i, iN, mX, iSa, iSb, iOld;

  iN= 1000; iSa= 5; iSb= 10;
  TrackTime({"Routine A", "Routine B"});
  TrackRoutine(FALSE);        // Set to TRUE to see which routine is
                              // entered
  for (i= 0; i < iN; ++i)
    {
      if (imod(i, 50)== 0)
        TrackReport();

      iOld= TrackTime(0);     // iOld gets value 1
      mX= lengthycalculation(iN, iSa);

      iOld= TrackTime(1);     // iOld gets value 0
      mX= lengthycalculation(iN, iSb);
      TrackTime(-1);          // Outside the routines, stop time
    }
}

For initialization, the routine TrackTime is called with an array of strings indication the different parts of the program that should be measured.

Within the program, commands like TrackTime(0) indicate that the first routine is entered, TrackTime(1) indicates the second routine etc. If needed, the output of the routine can be used to temporarily measure one routine, switching back to the old one using TrackTime(iOld) afterwards.

A negative integer as parameter for TrackTime stops the timing temporarily.

Each time that TrackReport() is called, a small report is written, indicating the total and percentage of time that was spent in the parts of the programs. The output of extrack.ox looks like

Time spent in routines
Routine ARoutine B
     3.46    11.57
     0.23     0.77

indicating that Routine B takes about three times as long as Routine A.

If a call is made to TrackRoutine(TRUE), then from that moment onwards the programs writes a notice when a specific routine is entered. This can be useful in finding an error in a program, to see where it gets stuck. The default is TrackRoutine(FALSE), no indication of the routine that is being entered.