Lead Solver Software

Lead Solver is a free (open source) software written by Matthew Kidd that tallies up how well each card does when led in terms of average tricks taken for the defense (for matchpoints) and how often the contract is set (for team play). It feeds a set of deals through Bo Haglund’s efficient double dummy solver and presents a tally of the results.

⇓ Download Now

Introduction

Double dummy simulations are an increasingly popular method of answering bridge questions. Indeed, the playing engine of several strong commercial bridge programs is to simply generate many possible layouts for the unseen hands, consistent with the bidding, and play the card that does best when averaged over the generated layouts. Best can be defined as either average tricks taken or the chance of setting the contract for matchpoint or team style of play respectively. This brute force approach has become more feasible as double dummy solvers have become more efficient and home computing power has continued to increase. It has similarities to the approach behind Deep Blue, the chess program which defeated Gary Kasparov in 1996, where depth of search combined with a fairly simple positional evaluator was chosen over a shallower search combined with a more sophisticated positional evaluator.

Recently David Bird and Taf Anthias published a pair of books, Winning Notrump Leads (2011) and Winning Suit Contract Leads (2012), which considered opening lead choices for typical hand types against frequently occurring auctions. They used double dummy analysis of hands consistent with the bidding to evaluate how well each lead fares. By judiciously swapping cards to understand when one type of lead does better than another, for example when the top of a sequence in a minor does better than low from Kxxx in a major, they derived useful guidelines and issued some challenges to conventional wisdom.

As explained in the acknowledgment section of each book, Anthias used Thomas Andrews’ Deal program and Bo Haglund’s DDS double dummy solver, combined with custom code to generate hands which are consistent with the auctions examined and to tally the results of the simulation.

DDS is built either as a Windows Dynamic-link Library (DLL) or a static library (for Mac OS X, Unix/Linux), which means DDS is a piece of code meant to be used by other programs rather than used directly. Lead Solver is functionally similar to some of the custom code Anthias must have written. It invokes DDS to evaluate each lead for a set of deals and then tallies up how well each lead does, generating a chart with columns analogous to the “Beats Contract” and “Avg Tricks” presented in their books. Lead Solver eliminates a step for analysts interested in double dummy simulations who don’t want to get their hands messy with C++ code.

License, supported platforms, and software setup

The Lead Solver software is released under the terms of GNU General Public License GPLv3. To compute the double dummy results it uses Bo Haglund’s free double dummy solver, DDS, released under the Apache 2.0 open source license. Lead Solver executables are provided for Windows, Mac OS X, and Debian (a flavor of Linux). It can be built for other platforms by compiling DDS for that platform and then compiling leadsolver.cpp and linking it against the DDS library.

Send feedback and bug reports to software@lajollabridge.com

Getting setup on Mac OS X

No special setup is required on Windows. On Mac OS X, you must copy the three dynamic libraries (libgcc_s.1.dylib, libgomp.1.dylib, libstdc++.6.dylib) from the mac-os-x folder of the download to the /usr/local/lib folder. This folder does not exist by default. Create it if necessary by starting a BASH shell using the Terminal app and entering the following commands:

sudo mkdir /usr/local
sudo chmod 775 /usr/local
sudo chgrp admin /usr/local
mkdir /usr/local/lib

You will need to enter your account password the first time you use sudo.

Now copy over the files and verify that they got copied.

cp ~/Downloads/Lead-Solver/mac-os-x/lib* /usr/local/lib
ls /usr/local/lib

Notes for technical people only: prior to XCode 4.2, XCode shipped with the GCC compiler. XCode 4.2 onward ships with Clang. In order to avoid breaking existing build processes, XCode symlinks gcc and g++ to clang. Normally this is fine since Clang is a good compiler and it has options that are very similar to the GCC options. However, Clang does not support OpenMP, the parallel processing language used by DDS to get the maximum functionality out of a multi-core machine. leadsolver-osx was compiled using true GCC, where GCC was installed via the Homebrew package manager. The libgomp.1.dylib library provides the OpenMP support and the remaining two libraries are needed because the code was compiled using GCC instead of Clang. If you have installed GCC yourself, you should already have the required libraries. If you want to keep the libraries somewhere other than /usr/local/lib, you can specify that location using the DYLD_LIBRARY_PATH environment variable, e.g. via:

export DYLD_LIBRARY_PATH=~/Downloads/Lead-Solver/mac-os-x

Running the Lead Solver program

Unzip all the files (or at least leadsolver.exe and dds.dll on Windows, leadsolver-osx on Mac OS X, or leadsolver-deb on Debian) into whatever folder you please. However don’t use your Deal folder if you have Thomas Andrews’ Deal program installed because Deal ships with an old version of dds.dll (from 2009) and Lead Solver uses features added in later versions of DDS. One option is to add a subfolder called leadsolver to your Deal program folder and unzip the files there.

Getting started on Windows

Start a DOS shell. On Windows XP you can start a DOS shell via Start (menu) → Programs → Accessories → Command Prompt; or more simply via Start (menu) → Run, type cmd, and press <enter>. On Windows 7 (and probably Vista), Microsoft has gone to more trouble to hide the “scary” DOS shell and even the Run Box. See this explanation of how to get the Run Box to appear.

From the DOS command line, switch to the directory the containing leadsolver.exe program (cd = “change directory”) as in the example below:

cd C:\Documents and Settings\username\My Documents   (typical for XP)
cd C:\Users\username\Documents   (typical for Win7 / Vista)

leadsolver

Invoking leadsolver without any command arguments will display the full list of available command line options (switches).

Getting started on Mac OS X

Start a BASH shell using the Terminal app. From the BASH shell switch to the directory the containing leadsolver-osx program (cd = “change directory”) as in the example below:

cd ~/Downloads/Lead-Solver
./leadsolver-osx

The ./ is important. Unless you alter the PATH environment variable, BASH will not search your current working directory for an executable.

Mac OS X and Linux users may wish to rename either leadsolver-osx or leadsolver-deb to leadsolver. The remaining examples below assume the executable is named leadsolver.exe or leadsolver.

If you see a message like “dyld: Library not loaded” when you try to run the program, check to see that you have followed the instructions in the section Getting setup on Mac OS X.

Processing a set of deals

Lead Solver operates on a file of deals where the hand on lead always contains the same cards and the cards in the other three hands are randomly chosen subject to the condition that they be consistent with the bidding. Ways to generate these files are discussed below. Lead Solver also requires a contract to determine trump (if any) and the number of tricks the defense needs to take to set the contact. Here is an example:

leadsolver 3N 2n-3n-2000-hands.pbn

This command says the contract is three no-trump and the deals are in the file 2n-3n-2000-hands.pbn. By default West is assumed to be on lead. However this may be changed using the -l (“leader”) switch, e.g. -l S puts South on lead.

Interpreting the output

The following is the output of a sample run.

C:\Users\matt\Documents\Bridge\Programs\Lead Solver> leadsolver 3N 2n-3n-2000-hands.pbn
Double dummy analysis completed for 2000 deals in 0 m 38 s (0.02 sec/deal ave)

                         Frequency of Tricks Taken
Ld   Avg  %Set      0   1   2   3   4   5   6   7   8   9  10  11  12  13
SA  3.02  15.35* [  0 215 652 527 299 153 113  34   7   0   0   0   0   0 ]
H6  2.99  10.30  [ 41 173 504 581 495 180  17   7   2   0   0   0   0   0 ]
H3  2.99  10.30  [ 41 173 504 581 495 180  17   7   2   0   0   0   0   0 ]
D4  2.92   9.05  [ 38 167 556 609 449 153  21   4   3   0   0   0   0   0 ]
D8  2.90   8.65  [ 40 170 566 603 448 147  19   4   3   0   0   0   0   0 ]
HT  2.87   8.40  [ 49 196 547 582 458 146  14   7   1   0   0   0   0   0 ]
S8  2.64   4.20  [ 44 180 739 649 304  59  17   5   3   0   0   0   0   0 ]
C8  2.42   4.15  [ 56 382 652 583 244  71   9   3   0   0   0   0   0   0 ]
CT  2.41   4.20  [ 57 382 674 560 243  69  12   3   0   0   0   0   0   0 ]
CQ  2.32   3.50  [ 61 395 740 535 199  54  14   2   0   0   0   0   0   0 ]

The first column indicates the card led, e.g SA means the ♠A. The second column gives the average number of tricks that the defense will take double dummy on this lead. The leads are sorted by decreasing number of average tricks. The third column gives the chance that the lead will set the contract. An asterisk marks the lead(s) with the best chance of setting the contract. The remaining columns give a breakdown of how often each lead resulted in the defense taking a given number of tricks. The Avg and %Set columns are calculated from these tallies.

Observe that only ten rows are reported. That is because only the highest of equivalent cards is reported. Leader’s full hand for this example was ♠A8 ♥T653 ♦8432 ♣QT8. Results for ♥5, ♦3, and ♦2 are not reported. At the table, the choice of leads from equivalents may affect partner’s assumptions and thus alter the defense but for double dummy calculations the solver already knows where every card is. For a more thorough analysis of this opening lead problem read the Two-Six Dream.

Lead Solver is very efficient because DDS is very efficient and Lead Solver instructs DDS to do exactly what it needs and nothing more. In particular, only one combination of denomination and seat is considered. This is more efficient than calculating the full set of 20 double dummy results (5 denominations × 4 seats) as is often done, and which is necessary when calculating the par contract. Also, Lead Solver instructs DDS to process the hands in batches to keep multiple cores busy on modern computers with multiple CPUs or multiple cores per CPU.

Format of the file of deals

Lead Solver has primitive parsing for deals. In version 1.0.2 and later, PBN format will be assumed if the file extension is .pbn or .PBN or if the -p switch is specified. In this scenario, the file will be scanned for deals with a full 52 cards, as in the examples below, and all other lines will be ignored.

[Deal "N:95.984.AKJ75.953 QJ762.J72.T6.J74 KT43.AKQ.Q9.AK62 A8.T653.8432.QT8"]
[Deal "N:QT3.J94.QJT97.73 J654.Q7.A5.J9542 K972.AK82.K6.AK6 A8.T653.8432.QT8"]
[Deal "N:72.A42.KQJ97.A54 T9654.97.T5.9632 KQJ3.KQJ8.A6.KJ7 A8.T653.8432.QT8"]

The first hand indicator, i.e. N:, is required by the PBN Standard and may be any of the four seats. Also in this example the West hand (in green) is always the same because we are examining how well each lead in a single West hand fares against deals consistent with the bidding.

When PBN is not assumed (or version 1.0.0 or 1.0.1 is used), blank lines are ignored and all other lines are assumed to be deals in GIB or PBN format with a full 52 cards. The GIB format looks like:

W:T5.K4.652.A98542 K6.QJT976.QT7.Q6 432.A.AKJ93.JT73 AQJ987.8532.84.K

The leading W: indicates which hand is specified first, where the remaining hands are clockwise around the table. The first hand indicator is optional. If it is left off, West is the default. See above for examples of the PBN format.

If PBN is not assumed, Lead Solver will be confused by other PBN fields like [Date "2013.11.10"].

If you are using Thomas Andrews’ Deal program the option -i format/pbn will dump the hands in PBN format with only [Deal lines, exactly as needed. The next section has more about this.

Generating deals

There are multiple deal generation programs. Thomas Andrews’ Deal program is open source and very flexible; however there is a bit of a learning curve. Unfortunately you are stuck with some programming at this stage, though fortunately not the low level C++ programming because Lead Solver has done that for you. Instead you write Tcl programs but luckily you don’t need to do a lot of programming.

Here is a sample Tcl program for the auction 2N 3N, where the West hand is always ♠A8 ♥T653 ♦8432 ♣QT8.

west is "A8 T653 8432 QT8" main { set hs [hcp south] reject unless {$hs>=20 && $hs<=21} # Note balanced excludes 5 cards suits in the majors. reject unless [balanced south] reject if { [hearts north] >= 4 } reject if { [spades north] >= 4 } # Assume responder trots out some gadget with 10+ cards in the minor suits. reject if { [diamonds north] + [clubs north] >= 10 } set hn [hcp north] reject unless {$hn>=5 && $hn<=10} # Assume responder makes a quantitative 4N bid one HCP light with a 5+ card minor. reject if { $hn==10 && ([diamonds north] >= 5 || [clubs north] >= 5) }; accept }

First this code fixes the West hand. Then it requires that the opening hand (South) be a balanced 20-21 HCP. The balanced command in Deal returns true if the hand is 4-3-3-3, 4-4-3-2, or 5-3-3-2 without a 5-card major. If you wish to simulate the scenario where opener can have a five card major and/or a six card minor, additional programming is required.

Finally the code limits the North hand (responder) to 3N bids by rejecting cases where North would pass, bid Stayman, transfer in a major, make a quantitative 4N bid, or trot out a special bid when holding a lot of minor suit cards. Here North is assumed to make a slam try with 11+ HCP on all hands and also on only 10 HCP when holding a five card or longer minor (we don’t have to consider 5+ card majors because those hands would transfer and that case has been handled above). You can of course change the HCP cutoff to simulate a more aggressive north. Or you might allow one or more four card majors with say 8-10 HCP on the assumption that North will try for a matchpoint top by suppressing the major suit (Kit Woolsey style). Or you can reject more responder hands with minor suit length if N-S are playing four suit transfers. And so on. You can make it as complicated as you like; however it often doesn’t have a big impact on the simulation results.

Ready to generates some deals? Let’s go.

deal -i 2n-3n.tcl -i format/pbn 1000 > 2n-3n.pbn

This generates 1000 deals meeting the criterion above and outputs them in the PBN format, ready for use by Lead Solver.

If you want to make the Tcl code more modular you can move the first line into a separate file, e.g. westhand.tcl, and then include both files on the command line:

deal -i westhand.tcl -i 2n-3n.tcl -i format/pbn 1000 > 2n-3n.pbn

Version history

Older versions of Lead Solver can be downloaded by clicking on the download arrow next to the version. The latest version is also always available from the Download Now button at the top of the page as well as here.

VersionDateMajor Changes
⇓ 1.0.202-Dec-2014 Include Mac OS X and Debian executables (previously only Windows)
Tidied up code for clean compilation on Mac OS X and Linux/Unix.
Switched to DDS 2.8.0 (runs about 15% faster).
Added -p (force PBN) switch.
⇓ 1.0.106-Nov-2014 Switched to DDS 2.7.0 (runs about 20% faster).
⇓ 1.0.029-Nov-2013 Original release.

Files included in the software distribution

The current program archive contains the files listed in the table below.

FilenamePurpose
leadsolver.exeExecutable program for Windows
leadsolver-osxExecutable program for Mac OS X
leadsolver-debExecutable program for Debian flavor of Linux
dds.dllDLL for Bo Haglund’s double dummy solver.
Necessary for running the Windows executable.
mac-os-x (folder)Folder of dynamic libraries (libgcc_s.1.dylib, libgomp.1.dylib, libstdc++.6.dylib).
Necessary to run the program on Mac OS X.
Changelog.txtRevision history
leadsolver.cppC++ program
dll.hC++ header file. Necessary for recompiling the code.

Command Line Help

Command line arguments inside [ ] are optional; for example [-l W|N|E|S] means the -l switch is optional but that if it is specified, one of W, N, E, or S must also be specified.

  Usage leadsolver [-p] [-q] [-v] [-l W|N|E|S] contract infname [outfname]

  Tallies how well the of each card in a hand (assumed to be fixed for a
  set of boards), does against a given contract, both in average tricks
  taken (for Matchpoints) and probability of setting the contract (for IMPS)
  using Bo Haglund's double dummy solver (dds.dll).

  -l  - Specify opening leader (W, N, E, or S). Default is W.
  -p  - Assume PBN format even if file extension is not .pbn or .PBN  
  -q  - Quiet. Do not show progress on the command line.
  -v  - Print version and compilation date on stdout.

  contract - Contract, e.g. 2H, 4N, or 7C (lowercase is also accepted)

  infname  - Filename of boards (one per line) in PBN / GIB format, e.g.
             one of these two formats.

     W:T5.K4.652.A98542 K6.QJT976.QT7.Q6 432.A.AKJ93.JT73 AQJ987.8532.84.K
     [Deal "N:762.KQ.QJ6.J9632 Q543.9874.T5.K75 432.A.AKJ93.JT73 ..."] (PBN)

     Hands are clockwise, starting with the one indicated by the first
     letter. If the first hand designator is missing, West is assumed (the
     GIBlib default). Extra characters on a line (e.g. existing double dummy
     results) are ignored.

  outfname - Output filename. If not specified, output is written to STDOUT
             All other messages are written to STDERR.

  Open source released under the GNU General Public License GPLv3.
  Written by Matthew Kidd (San Diego, CA)

  Online documentation is located at:
  http://www.lajollabridge.com/Software/Lead-Solver/Lead-Solver-About.htm