SolveBoard(3)						     Library Functions Manual						     SolveBoard(3)

NAME

       InitStart, SolveBoard, SolveBoardPBN, CalcDDtable, CalcDDtablePBN - calculate number of possible tricks in a Bridge hand

SYNOPSIS

       #include <dds.h>

       void InitStart(int gb_ram, int ncores);

       int SolveBoard(struct deal, int target, int solutions, int mode, struct futureTricks *futp, int threadIndex);

       int SolveBoardPBN(struct dealPBN, int target, int solutions, int mode, struct futureTricks *futp, int threadIndex);

       int CalcDDtable(struct ddTableDeal tableDeal, struct ddTableResults *tablep);

       int CalcDDtablePBN(struct ddTableDealPBN tableDealPBN, struct ddTableResults *tablep);

DESCRIPTION

       Short description of the DLL functions supported in Double Dummy Problem Solver 2.1.2

       InitStart

       Initialize data structures for SolveBoard.

       If  either gb_ram or ncores are zero, autoconfiguration is done.  This is currently only supported on Windows; other platforms exit fatally
       when attempted.

       SolveBoard

       Before SolveBoard can be called, a structure of type "futureTricks" must be declared.

       SolveBoard returns a status integer, "no fault" means the DLL supplies the trick data in the "futureTricks" type structure.  Status codes:
	  1=No fault
	 -1=Unknown fault
	 -2=No of cards = 0
	 -3=target > Number of tricks left
	 -4=Duplicated cards
	 -5=target < -1
	 -7=target > 13
	 -8=solutions < 1
	 -9=solutions > 3
	-10=No of cards > 52
	-11=Not used
	-12=Suit or rank value out of range for deal.currentTrickSuit or deal.currentTrickRank
	-13=Card already played in the current trick is also defined as a remaining card to play
	-14=Wrong number of remaining cards for a hand
	-15=threadIndex < 0 or > 15

       Structure "deal" defines all data needed to describe the deal to be analyzed.
	struct deal {
	  int trump;   /* I.e. which suit that is trump or if contract is NT, Spades=0, Hearts=1, Diamonds=2, Clubs=3,	NT=4 */
	  int first;	  /* 0-3, 0=North, 1=East, 2=South, 3=West , Leading hand for the trick.*/
	  int currentTrickSuit[3];  /* 0-2 for up to 3 cards in the order played */
	  int currentTrickRank[3];  /* 2-14 for up to 3 cards */
	  unsigned int remainCards[4][4]; /* 1st index hand (0-3), 2nd index suit (0-3), values as bitstring of ranks bit 0=0, bit 1=0, bit 2=rank
       2, . bit 14=rank 14, bit 15=0 for cards remaining after already played cards (cards already played to the current trick are not included in
       this bitstring).
	The decimal value for a card then range between 4 (=rank 2) and 16384  (Ace=rank 14). */
	};

       Parameter "target" is the number of tricks to be won by the side to play, -1 means that the program shall  find	the  maximum  number.  For
       equivalent  cards only the highest is returned.

       Parameter "solutions" defines how many card solutions that SolveBoard must return:

       target=1-13, solutions=1:
	      Returns  only one of the cards. Its returned score is the same as target whentarget or higher tricks can be won. Otherwise, score -1
	      is returned if target cannot be reached, or score 0 if no tricks can be won.

       target=-1, solutions=1:
	      Returns only one of the optimum cards and its score.

       target=0, solutions=1:
	      Returns only one of the cards legal to play with score set to 0.

       target 1-13, solutions=2:
	      Return all cards meeting target. Their returned scores are the same as target when target or higher tricks can  be  won.	Otherwise,
	      only one card is returned with score -1 if target cannot be reached, or score 0 for all cards legal to play if no tricks can be won.

       target -1, solutions=2:
	      Return all optimum cards with their scores.

       target=0, solutions=2:
	      Return all cards legal to play with scores set to 0.

       target irrelevant, solutions=3:
	      Return all cards that can be legally played with their scores in descending  order.

       Parameter "mode" defines the DLL mode of operation.

       mode=0 Do  not  search  to find the score if the hand to play has only one card, including its equivalents, to play. Score is set to -2 for
	      this card, indicating that there are no alternative cards. If there are multiple choices for cards to play, search is done  to  find
	      the score. This mode is very fast but you don't

       mode=1 Always search to find the score. Even when the hand to play has only one card,  with possible equivalents, to play.  For both mode=0
	      and mode=1: If the preceding SolveBoard call had the same trump suit and the same or similar deal, except for deal.first,  then  the
	      transposition  table contents is reused from the preceding SolveBoard call. Setting mode=2 is no longer needed in this case, but can
	      still be done for backwards compatibility.

       mode=2 As for mode=1, but the transposition table contents is reused from the preceding SolveBoard call.  It is the responsibility  of  the
	      programmer  using  the  DLL  to ensure that reusing the table is safe in the actual situation. Example: Deal is the same, except for
	      deal.first. Trump suit is the same.
	       1st call:  SolveBoard(deal, -1, 1, 1, &fut, 0),	deal.first=1, i.e. East leads.
	       2nd call:  SolveBoard(deal, -1, 1, 2, &fut, 0),	deal.first=2, i.e. South leads.
	       3rd call:  SolveBoard(deal, -1, 1, 2, &fut, 0),	deal.first=3, i.e. West leads.
	       4th call:  SolveBoard(deal, -1, 1, 2, &fut, 0),	deal.first=0, i.e. North leads.

	struct futureTricks { /* The DLL provides the score (number of tricks) that can be won by the card to play defined by its suit	and  rank.
       Array of all alternative cards. */
	  int nodes;	     /* Number of searched nodes */
	  int cards;	     /*  No of alternative cards  */
	  int suit[13];      /* 0=Spades, 1=Hearts, 2=Diamonds, 3=Clubs */
	  int rank[13];      /* 2-14 for 2 through Ace */
	  int  equals[13];     /*  Bitstring  of ranks for equivalent lower rank cards. The decimal value range between 4 (=2) and 8192 (King=rank
       13).  When there are several "equals", the value is the sum of each "equal". */
	  int score[13];     /* -1 indicates that target was not reached, otherwise target or max numbe of tricks */
	};

       Parameter "threadIndex" defines the identity of the thread used when calling SolveBoard.  Maximum 16 threads can call SolveBoard in  paral-
       lel, threadIndex must be an integer of the range 0..15.

       SolveBoard is thread-safe, so several threads (max 16) can call SolveBoard in parallel.

       SolveBoardPBN

       In  SolveBoardPBN  the  remaining  cards  in  the  deal	information are given in PBN text format (e.g. W:T5.K4.652.A98542 K6.QJT976.QT7.Q6
       432.A.AKJ93.JT73 AQJ987.8532.84.K) instead of using bits 2-14 in an integer array. Otherwise, SolveboardPBN is identical to SolveBoard.

	struct dealPBN {
	  int trump;
	  int first;
	  int currentTrickSuit[3];
	  int currentTrickRank[3];
	  char remainCards[80];   /* First character identifies the hand having the cards given first
					in the string, then the cards of the other hands are given in a
					clock-wise order, see example above. Null characters fill out
					the character array at the end. */
	};

       CalcDDtable

       CalcDDtable calculates the double dummy values of the initial 52 cards for all the 20 trump suit/declarer hand combinations.

       Before CalcDDtable can be called, a structure of type "ddTableResults" must be declared.  CalcDDtable returns a status integer, "no  fault"
       means the DLL supplies the double dummy scores in the "ddTableResults" type structure.  Status codes:
	  1=No fault,
	  Other status codes are errors, with codes equal to SolveBoard status codes.

       Structure "ddTableDeal" defines the dealt cards to be analyzed.

	struct ddTableDeal {
	  unsigned int cards[4][4];   /* 1st index is hand, 2nd index is suit, same coding as for deal.remainCards for SolveBoard. */
	};

	struct ddTableResults { /* For each combination trump suit / declarer hand, the DLL provides the double dummy score. */
	  int  resTable[5][4];	 /*  1st  index is trump (0=Spades, 1=Hearts, 2=Diamonds, 3=Clubs, 4=No Trump 2nd index is declarer hand, 0=North,
       1=East, 2=South, 3=West */
	};

       CalcDDtablePBN

       In CalcDDtablePBN the remaining cards in the deal information are given in PBN text format, see the description	above  for  SolveBoardPBN.
       Otherwise, CalcDDtablePBN is identical to CalcDDtable.

	struct ddTableDealPBN {
	  char cards[80];
	};

Revision History
       Rev A, 2006-02-25   First issue.

       Rev B, 2006-03-20   Updated issue.

       Rev C, 2006-03-28   Updated issue. Addition of the SolveBoard parameter "mode".

       Rev D, 2006-04-05   Updated issue. Usage of target=0 to list all cards that are legal to play.

       Rev E, 2006-05-29   Updated issue. New error code -10 for number of cards > 52.

       Rev F, 2006-08-09   Updated issue. New mode parameter value = 2. New error code -11 for calling SolveBoard with mode = 2 and forbidden val-
       ues of other parameters.

       Rev F1, 2006-08-14  Clarifications on conditions for returning scores for the different combinations of the values  for	target	and  solu-
       tions.

       Rev F2, 2006-08-26  New error code -12 for wrongly set values of deal.currentTrickSuit and deal.currentTrickRank.

       Rev G, 2007-01-04   New DDS release 1.1, otherwise no change compared to isse F2.

       Rev H, 2007-04-23   DDS release 1.4, changes for parameter mode=2.

       Rev I, 2010-04-10   DDS release 1.2, multi-thread support.

       Rev J, 2010-05-29   DDS release 2.1, OpenMP support, reuse of previous DD transposition table results of similar deals.

       Rev K, 2010-10-27   Correction of fault in the description:  2nd index in resTable of the structure ddTableResults is declarer hand.

       Rev L, 2011-10-14   Added SolveBoardPBN and CalcDDtablePBN.

								      2010-10							     SolveBoard(3)