Updated: July 20, 2003
Whenever an user need any information, he/she can use functions which are in the below Function Summary table.
In order to write a new strategy, do first
1) Change structure Strategy
in Strategy.h so that it can hold parameters which are necessary for your
new strategy.
2) Change Strategy_init()
so that the function can set initial values of parameters for your strategy.
3) Change specifyStrategy()
so that it can properly process command-line arguments.
4) Modify printStrategy().
Then you can write your strategy in updateAgentOrder.
Contains information about a client who is connected to pxs, which includes present value, shares, cash, agent number, etc.
Contains basic information about current market(pxs), which includes currnet market price, volume, the number of orders, etc..
Contains some statistical information for traders, which
includes quartile values, etc. There may be 2 different MarketStatistics.
One is computed based on ISLAND queues, the other is computed based on pxs(simulator)
queues.
Contains parameters for an user's own strategy.
This summarizes all functions which users can call or whose content users should
provide.
int | getAgentNumber
(ClientState
*cState)
Returns agent number of this agent. |
float | getIslLastPrice
(MarketState
*mState)
Returns current Island market price. |
float | getSimLastPrice
(MarketState
*mState)
Returns current Simulator market price. |
float | getVolume
(MarketState
*mState)
Returns how many shares have been traded since the market opens today. |
int | getOrders
(MarketState
*mState)
Returns how many orders have been placed since the market opens today. |
float | getBuyQuartile
(MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in buy side queue. |
float | getSellQuartile
(MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in sell side queue. |
float | getIslandBuyQuartile
(MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in buy side queue. |
float | getIslandSellQuartile
(MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in sell side queue. |
int | getTotalBuyVolume
(MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in buy queue . |
int | getTotalSellVolume
(MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in sell queue. |
int | getTotalVolume
(MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in both buy and sell queues. |
int | getMatchBuyVolumeOfAllAgents
(MarketState
*mState)
Returns how many volumes of buy orders placed by all agents matched. |
int | getMatchSellVolumeOfAllAgents
(MarketState
*mState)
Returns how many volumes of sell orders placed by all agents matched. |
int | getTotalMatchVolumeOfAllAgents
(MatketState
*mState)
Returns how many volumes placed by all agents matched. |
float | MarketStatistics_getWeightedMarketAverage (const
MatketState
*mState, MarketStatistics
*stat)
Returns the weighted market average price for the corresponding market statistics of the current market. |
int | getCurrentShare
(ClientState
*cState)
Returns how many shares this agent holds currently. Negative shares are allowed. |
float | getCurrentCash
(ClientState
*cState)
Returns cash amount which this agent holds currently. Negative cash is allowed. |
float | getIslPresentValue
(ClientState
*cState)
Returns Island present value(i.e. profit and loss) of fund which this agent manages. |
float | getSimPresentValue
(ClientState
*cState)
Returns Simulator present value(i.e. profit and loss) of fund which this agent manages. |
int | updateAgentOrder
(ClientState
*cState, MarketState
*mState, MarketStatistics
*pxsStat, MarketStatistics
*iStat, Strategy
*myStrategy)
Is the function where users should put their own strategies. |
int | getNumOfElementsInBuyQueue
(MarketState
*mState)
Returns how many orders exists in buy side queue. |
int | getNumOfElementsInSellQueue
(MarketState
*mState)
Returns how many orders exist in sell side queue. |
float * | getOrderPricesInBuyQueue
(int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in buy side queue. |
float * | getOrderPricesInSellQueue
(int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in sell side queue. |
int * | getOrderSharesInBuyQueue
(int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in buy side queue. |
int * | getOrderSharesInSellQueue
(int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in sell side queue. |
int | buyOrder
(float price, int share, ClientState
*cState, MarketState
*mState)
Places a buy order. |
int | sellOrder
(float price, int share, ClientState
*cState, MarketState
*mState)
Places a sell order. |
int | withdraw
(int type, int ref_no, ClientState
*cState, MarketState
*mState)
Request withdrawal of an order. |
simTime_t | simTime (const MarketState
*mState, simTime_t *t)
Returns the value of simulator time in seconds since "midnight". |
double | simDiffTime
(simTime_t time1, simTime_t time0)
Returns the number of seconds elapsed between time time1 and time time0. |
int * | getRefNosOfMyBuyOrders
(ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference number of buy orders of this agent. |
int * | getRefNosOfMySellOrders
(ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference number of sell orders of this agent. |
float | getPriceOfThisBuyOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this buy order. |
float | getPriceOfThisSellOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this sell order. |
int | getShareOfThisBuyOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this buy order. |
int | getShareOfThisSellOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this sell order. |
int | getNumOfMyBuyOrders
(ClientState
*cState, MarketState
*mState)
Returns the number of orders of this agent in buy queue. |
int | getNumOfMySellOrders
(ClientState
*cState, MarketState
*mState)
Returns the number of orders ot this agent in sell queue. |
void | specifyStrategy
(int argc, char **argv, Strategy
*myStrategy)
Sets parameters for user's strategy by processing command-line arguments. |
void | Strategy_init
(Strategy
*myStrategy)
Initialize parameters for user's strategy. |
void | printUsage
(void)
Prints usage. If an user made any change in structure Strategy, it should be modified so that it can print correct usage. |
void | printStrategy
(Strategy
*myStrategy)
Prints summarized strategy before mytrader starts running. |
int getAgentNumber (ClientState
*cState)
Returns agent number of this agent.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
agent number of this agent.
float getIslLastPrice (MarketState
*mState)
Returns current Island market price.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
current Island market price.
float getSimLastPrice (MarketState
*mState)
Returns current Simulator market price.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
current Simulator market price.
float getVolume (MarketState
*mState)
Returns how many shares have been traded since the market opens today.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
current market volume.
int getOrders (MarketState
*mState)
Returns how many orders have been placed since the market opens today.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders placed today.
float getBuyQuartile (MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in buy side queue.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat - pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
index - 1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), or 4(for
100% quartile).
Returns:
a buy quartile value of real and virtual orders.
float getSellQuartile (MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in sell side queue.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat - pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
index - 1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), 4(for
100% quartile).
Returns:
a sell quartile value of real and virtual orders.
float getIslandBuyQuartile (MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in buy side queue.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
iStat - pointer to MarketStatistics
which is passed as 4th argument of updateAgentOrder.
index - 1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), 4(for
100% quartile).
Returns:
a buy quartile value of real orders.
float getIslandSellQuartile (MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in sell side queue.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
iStat - pointer to MarketStatistics
which is passed as 4th argument of updateAgentOrder.
index - 1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), 4(for
100% quartile).
Returns:
a buy quartile value of real orders.
int getTotalBuyVolume (MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in buy queue.
Parameters:
mState
- pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat - pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
Returns:
total volume of all orders in buy queue.
int getTotalSellVolume (MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in sell queue.
Parameters:
mState
- pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat - pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
Returns:
total volume of all orders in sell queue.
int getTotalVolume (MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in both buy and sell queue.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat - pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
Returns:
total volume of all orders in both buy and sell queue.
int getMatchBuyVolumeOfAllAgents (MarketState
*mState)
Returns how many shares of buy orders placed by all agents matched.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of buy side shares which were placed by all agents and matched.
int getMatchSellVolumeOfAllAgents (MarketState
*mState)
Returns how many shares of sell orders placed by all agents matched.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of sell side shares which were placed by all agents and matched.
int getTotalMatchVolumeOfAllAgents (MarketState
*mState)
Returns how many shares of all orders placed by all agents matched.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of all shares which were placed by all agents and matched.
int MarketStatistics_getWeightedMarketAverage (const MatketState
*mState, MarketStatistics
*stat)
Returns the weighted market average price for the corresponding market statistics of the current market.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
stat - pointer to MarketStatistics which is either the 3rd or the 4th argument of updateAgentOrder. The value will be computed based on the PXS queues if the 3rd argument of updateAgentOrder is passed, or based on the Island queues if the 4th argument of updateAgentOrder is passed.
Returns:
the weighted market
average price for the corresponding market statistics of the current market.
int getCurrentShare (ClientState
*cState)
Returns how many shares this agent holds currently. Return value may be negative.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
the number of current holding shares of this agent.
float getCurrentCash (ClientState
*cState)
Returns cash amount which this agent holds currently. Return value maybe negative.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
cash amount which this agent holds.
float getIslPresentValue (ClientState
*cState)
Returns Island present value of fund which this agent manages. The value is calculated based on the Island last price.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
present Island value of the fund which this agent manages.
float getSimPresentValue (ClientState
*cState)
Returns Simulator present value of fund which this agent manages. The value is calculated based on the Simulator last price.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
present Simulator value of the fund which this agent manages.
int updateAgentOrder (ClientState
*cState, MarketState
*mState, MarketStatistics
*pxsStat, MarketStatistics
*iStat, Strategy
*myStrategy)
Is the function where users should put their own strategies.
Parameters:
cState - pointer to ClientState
which contains information about this agent.
mState - pointer to MarketState
which contains basic information about current market(on pxs).
pxsStat - pointer to MarketStatistics
which contains statistical information computed from pxs order book.
iState - pointer to MarketStatistics
which contains statistical information computed from ISLAND order book.
myStrategy - pointer to Strategy
which conatains parameters for user's strategy.
Returns:
1 if any order is placed, otherwise 0.
int getNumOfElementsInBuyQueue (MarketState
*mState)
Returns how many orders exists in buy side queue.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders in current buy queue.
int getNumOfElementsInSellQueue (MarketState
*mState)
Returns how many orders exists in sell side queue.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders in current sell queue.
float *getOrderPricesInBuyQueue (int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in buy side queue.
Parameters:
number - the number of order prices a user wants to get from the top of the buy
queue. This cannot be greater than the return value of getNumOfElementsInBuyQueue.
If the return value of getNumOfElementsInBuyQueue
is used for number, the return value of this function can access prices of all
orders in the buy queue.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains price information of each order in buy side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another sub-routine.
Usage for free should be as follows.
float *p_arr;
:
p_arr = getOrderPricesInBuyQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
float *getOrderPricesInSellQueue (int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in sell side queue.
Parameters:
number - the number of order prices a user wants to get from the top of the
sell queue. This cannot be greater than the return value of getNumOfElementsInSellQueue.
If the return value of getNumOfElementsInSellQueue
is used for number, the return value of this function can access prices of all
orders in the sell queue.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains price information of each order in sell side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another sub-routine.
Usage for free should be as follows.
float *p_arr;
:
p_arr = getOrderPricesInSellQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int *getOrderSharesInBuyQueue (int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in buy side queue.
Parameters:
number - the number of order shares an user wants to get from the top of the buy
queue. This cannot be greater than the return value of getNumOfElementsInBuyQueue.
If the return value of getNumOfElementsInBuyQueue
is used for number, the return value of this function can access shares of all
orders in the buy queue.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains share information of each order in buy side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another sub-routine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getOrderSharesInBuyQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int *getOrderSharesInSellQueue (int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in sell side queue.
Parameters:
number - the number of order shares an user wants to get from the top of the
sell queue. This cannot be greater than the return value of getNumOfElementsInSellQueue.
If the return value of getNumOfElementsInSellQueue
is used for number, the return value of this function can access shares of all
orders in the sell queue.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains share information of each order in sell side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another sub-routine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getOrderSharesInSellQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int buyOrder (float price, int share, ClientState
*cState, MarketState
*mState)
Places a buy order.
Parameters:
price - price at which an user wants to buy.
share - share amount an user wants to buy.
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
reference number of this order.
int sellOrder (float price, int share, ClientState
*cState, MarketState
*mState)
Places a sell order.
Parameters:
price - price at which an user wants to sell.
share - share amount an user wants to sell.
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
reference number of this order.
int withdraw (int type, int ref_no, ClientState
*cState, MarketState
*mState)
Request withdrawal of an order.
If the owner of the order isn't identical to the person who requests this
withdrawal, or the order doesn't exist in proper queue, it will
be rejected. And even though
the requeust is accepted, it means just it'll be processed. Note that
partial cancellation of an order is not allowed yet.
Parameters:
type - should be "BUY" or "SELL"
ref_no - reference number of the order which the agent wants to withdraw.
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
1 if the request is accepted. It may be rejected later.
0 if the request is rejected.
simTime_t simTime (const MarketState
*mState, simTime_t *t)
Returns the time in seconds since "midnight," where "midnight" is defined relative to the simulator execution. If t is non-NULL, the return value is also stored in the memory pointed to by t. "simTime.h" needs to be included for using this function.
Parameters:
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
t - if non-NULL, the return value is also stored in the memory pointed to by this pointer.
Returns:
the value of simulator time in seconds since "midnight".
double simDiffTime (simTime_t time1, simTime_t time0)
Returns the number of seconds elapsed between time time1 and time time0. "simTime.h" needs to be included for using this function.
Parameters:
time1 - later timestamp.
time0 - earlier timestamp.
Returns:
the number of seconds elapsed between time time1 and time time0.
int *getRefNosOfMyBuyOrders (ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference numbers of buy orders of this agent.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains reference numbers of buy orders of this
agent.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another sub-routine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getRefNosOfMyBuyOrders
(cState, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int *getRefNosOfMySellOrders (ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference numbers of sell orders of this agent.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains reference number of sell orders of this
agent.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another sub-routine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getRefNosOfMySellOrders
(cState, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
float getPriceOfThisBuyOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this buy order.
Parameters:
ref_no - reference number of the order which this agent wants to get its price.
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the price of this buy order.
float getPriceOfThisSellOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this sell order.
Parameters:
ref_no - reference number of the order which this agent wants to get its price.
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the price of this sell order.
int getShareOfThisBuyOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this buy order.
Parameters:
ref_no - reference number of the order which this agent wants to get its price.
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the share of this buy order.
int getShareOfThisSellOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this sell order.
Parameters:
ref_no - reference number of the order which this agent wants to get its price.
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the share of this sell order.
int getNumOfMyBuyOrders (ClientState
*cState, MarketState
*mState)
Returns the number of orders of this agent in buy queue.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders of this agent in buy queue.
int getNumOfMySellOrders (ClientState
*cState, MarketState
*mState)
Returns the number of orders of this agent in sell queue.
Parameters:
cState - pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState - pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders of this agent in sell queue.
void specifyStrategy (int argc, char **argv, Strategy
*myStrategy)
Sets parameters for user's strategy by processing command-line arguments.
Parameters:
argc - the number of command-line arguments.
argv - poiter to pointer to command-line arguments.
myStrategy - pointer to Strategy
which is passed as 5th argument of updateAgentOrder.
void Strategy_init (Strategy
*myStrategy)
Initialize parameter for user's strategy.
Parameters:
myStrategy - pointer to Strategy
which is passed as 5th argument of updateAgentOrder.
void printUsage (void)
Prints usage of mytrader program
which an user makes changes corresponding to his/her strategy.
Prints summarized strategy before
mytrader starts running.
This summarizes all deprecated functions which appear in the previous
versions of API. They are kept for backwards compatibility. Users are highly
recommended to use their corresponding updated version.
|
|
float | getLastPrice (MarketState
*mState)
Returns current Island market price. Replaced by getIslLastPrice (MarketState *mState). |
float | getPresentValue
(ClientState
*cState)
Returns Island present value(i.e. profit and loss) of fund which this agent manages. Replaced by getIslPresentValue (ClientState *cState). |