NOTES ON PXS BETA VERSION
Luis Ortiz
Michael Kearns

First of all, the beta version of the simulator is 

/home/pxs/bin/pxs.beta

So, please, to run the beta version, run that executable. Although the beta version accepts (new) additional command-line arguments (See below), the program will work with the same command-line argumens that you have been using thus far with pxs! For instance, in order to use pxs.beta just as you have been using pxs, the only change that you would have to make to your own script file (the one you have been using to run the server and your client) is to  simply change any reference of pxs in your script file to pxs.beta. (In addition, you might need to possibly add a sleep command between the invocation of the server and your client in your script. Please see mini FAQ for more detailed information.)

As a start, please take a look at the directory /pxs/new-clients-source/ which may contain new versions of your strategies (more information below.)

If a file named makefile.strategy exists in your strategy's source-code directory (given above), that means that your makefile has been modified and therefore that "makefile.strategy" will be your new makefile under the new (beta) version of the simulator. Please copy appropriately to your home directory.

Otherwise, you can just copy the new general makefile

/home/pxs/bin/makefile.beta

that is provided for you to use.

NOTE: Please ignore other files makefiles.* that might be currently present in that directory. If a fname_prefix.BAK file exists there that means the file with the corresponding prefix name fname_prefix was modified. Use the unix command diff to look at the differences.

NEW TIME-HANDLING MECHANISMS

We have created new simulator time functionality. Any notion of time used in your strategies (sleeping, checking the wallclock, etc.) must use the new time facilties.

In general, all you have to do is to add the following to your strategy.c file:

  • Add the following include directive to the header include section near the top of your file:

    #include "simTime.h"

  • Replace time_t anywhere in your the file to simTime_t, and replace any time and difftime function calls by calls to simTime and simDiffTime. For example, the following piece of code (in the body of the function updateAgentOrder in strategy.c):

    time_t current_time;
    time_t last_time;
    double time_diff;
    current_time = time(NULL);
    /* assuming last_time has being appropriately defined/set! */
    time_diff = difftime(current_time, last_time);
    last_time = current_time;

    should now be replaced by

    simTime_t current_time;
    simTime_t last_time;
    double time_diff;
    /* NOTE: mState is a pointer to an instance of the market state
    which is defined (since it is given as an argument to
    updateAgentOrder). simTime needs mState as an argument because the
    simulator time is part of the market state. */
    current_time = simTime(mState, NULL);
    /* assuming last_time has being appropriately defined/set! */
    time_diff = simDiffTime(current_time, last_time);
    last_time = current_time;

    If you call time functions outside updateAgentOrder, you need to modify your code appropriately.

    IMPORTANT NOTE:
    The simulator time is only obtained through simTime, which needs mState. So if you really need to initialize time values for your strategies to the very first time obtained from the simulator (or some other more specific reference times), you have to keep track yourself of when that is in order to obtain the desired initial values. Keep in mind that the server can tell the client that the simulator time is 0 (meaning "midnight") because the server might not have been able to properly set its time yet! (See below for more info.)

    You can find a more detailed description of the new simulator time facilities here.

    FINAL REMARKS ON TIME FUNCTIONALITY AND YOUR STRATEGIES

  • We only adapted code for strategies that seem to *logically* use the built-in/standard C time facility available through time.h (as opposed to strategies that "use" the unix time facilities without any *logical* effect on their program execution). Those who later want to change their strategies to use some notion of time must adapt their source code to use the provided simulator time facilities!
  • DISCLAIMER: The limited adaptation was only done for testing purposes. So even for those people whose strategy's source code we adapted, there is no gurantee that we did it correctly, so you might want to take a look at the code yourself to make sure the logic has not changed.

    ADDITIONAL FUNCTIONALITY

    There will be a new (extended) API coming up soon! Apart from the new time facilities, there are some new functions of which you should be particularly aware.

    (NOTE: In the following discussion, we are not including the function's arguments when refering to a function, therefore ignoring that those functions take appropriate arguments, for simplicity. Refer to the API for a description of how to properly use those functions.)

  • getSimLastPrice() returns the price of the last (order) match executed in the *simulator*. Currently, getLastPrice() returns the price of the last (order) match executed on *Island*. From now on, if you really want to get the Island last price, use getIslLastPrice() instead. (Do not rely on getLastPrice() to get the Island last price as it might change in the near future! It's only being kept for backwards compatibility.)

  • getSimPresentValue() returns the valuation of your current holdings based on the simulator's last price (and assuming infinite "liquidity"). As in the case of getLastPrice() described above, currently, getPresentValue() returns the valuation based on Island's last price. From now on you should use getIslPresentValue() to be sure to get the Island-based valuation as the return value of getPresentValue() might change in the near future!

    •   ADDITIONAL PXS.BETA/MYTRADER COMMAND-LINE FLAGS

  • There is now a verbose mode for the output of the simulator. For your clients' ouput, you can get it by using -V as the *last* command-line input flag to your program. (To keep it compatible with your current strategies, this flag *must* be the last flag. It is automatically removed by the client's core process and therefore you won't see any "references" to it in argv[] or argc, which are passed to specifyStrategy().) This flag can also be used as an input to pxs.beta  (the beta version of the simulator). The verbose mode will produce output files that look more like the ones you have been getting in the current simulator, and therefore can be VERY large. So beware if you use this flag! 

  • The simulator can now be run in synchronous mode. This is how it works. Add the command line flag -s num_clients, where num_clients is an integer given the number of clients that will connect to the server, as input to pxs.beta. Then run that number of clients; the server (pxs.beta) won't continue until all the clients you specified connect. Once they have connected the server will synchronize with them as follows. At every round of the simulator server (i.e., after every Island book is processed), the server will communicate with each client (i.e., send the current books and other simulator information and wait until the client is done with that round of processing the books and receive any possibly new orders the client has placed), one at a time and in the same order that the clients connected! Hence, for every simulator server iteration, there will be a corresponding client iteration. So clients will be able to see the books at every server iteration and act on it. Note that because the server waits for a response of each client before continuing, if at least one of the connecting client's strategy takes a long time to finish a round (i.e., updateAgentOrder takes a long time to return), the simulation will be slowed down accordingly. So try to be aware of this when you use this feature.

    PLOTTING SCRIPTS

    The output file format of the executables has changed, primarily because the information originally provided has been extended with other related information (such as the simulator and Island's inside market, the simulator price, the simulator time, etc.). In order to get plots with the *same* information that getplots computes now, you need to copy the files /home/pxs/bin/getplots.beta and /home/pxs/bin/getclientout to your home directory. (You can name your copy of getplots.beta just getplots.) Now, you can use mergeplots as you do now to get plots in a single page.

    We are also providing a script getpxs to get information out of the simulator output file. The script is simple enough that it is easy to deduce what it does from looking at the file itself. Alternatively, refer to the old web page documentation for more info on this script.

    There is more information in the new version of the output files that the scripts above do not compute. For now, we are leaving it to you to adapt the scripts (including auxiliary files such as plotps.gnu, mergeplots, and merge.tex, etc.) to obtain/plot other data in the output files. If you take a look at the scripts file, you'll see that it is not hard to modify them to compute other information of interest to you.

    MEMORY MANAGEMENT HINTS

    Several memory leaks were found in some of the clients' source code provided. A common cause was that people forgot to free the memory allocated for the array returned by the getOrderPrices/Share functions, etc. Please read the warning associated with using function in the API.

    In general, one way to detect memory leaks is to use the command top to monitor the size of the processes. For instance, in gradient, top -Uusername will plot the top processes of user username. For a days worth of historical simulation with about 5-6 clients connected, the processes pxs.beta, the simulator's server typically uses at most 5-6Mb, and in general sizes in Mb in the single digits! The exact number depend on how much activity there is and how long it takes clients to go "through a round" (i.e., from the time updateAgentOrder begins to the time it returns). So, if your client process shows up using a somewhat larger amount of memory than that of pxs, and it seems to be growing significanlty with time, then your program is likely to have a memory leak. So try to correct it, since this can cause problems during simulations/competitions and, if the leak is severe, which some of the one we found were, your executable can cause other programs running in gradient to crash because of lack of memory. Please beware.