Provided by: libdds-dev_2.1.1+ddd105-2_amd64 bug

NAME

       InitStart, SolveBoard, CalcDDtable - 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 CalcDDtable(struct ddTableDeal tableDeal, struct ddTableResults *tablep);

DESCRIPTION

       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 parallel, threadIndex must be an integer of  the
       range 0..15.

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

       CalcDDtable

       CalcDDtable  calculates  the  double  dummy  values of the initial 52 cards for all the 20
       trump suit/leading 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 / leading 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 leading hand, 0=North, 1=East, 2=South, 3=West */
        };

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 values of other parameters.

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

       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.

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

                                             2010-10                                SolveBoard(3)