NAME
SolveBoard, CalcDDtable - calculate number of possible tricks in a
Bridge hand
SYNOPSIS
#include <dds.h>
int SolveBoard(struct deal, int target, int solutions, int mode, struct
futureTricks *futp, int threadIndex);
int CalcDDtable(struct ddTableDeal tableDeal, struct ddTableResults
*tablep);
DESCRIPTION
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
dealâ defines all data needed to describe the deal to be analyzed.
Structure â 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, â The decimal value for a card then range between 4 (=rank 2) and
16384 (Ace=rank 14). */
};
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.
solutionsâ defines how many card solutions that SolveBoard must return:
Parameter â Parameter â.TP 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.
modeâ defines the DLL mode of operation.
Parameter â.TP 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
t
to find the score. This mode is very fast but you donâ.TP 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 â int score[13]; /* -1 indicates that
target was not reached, otherwise target or max numbe of tricks */ };
threadIndexâ defines the identity of the thread used when calling SolveBoard.
Parameter â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.
ddTableDealâ defines the dealt cards to be analyzed.
Structure â
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.
modeâ.
Rev C, 2006-03-28 Updated issue. Addition of the SolveBoard parameter
â 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.
2010-04 SolveBoard(3)