Bridge, Out Ahead website
Bridge, Out Ahead website
User Guide
Bridge, Out Ahead on Substack is a blog (you are reading a post on that blog right now). This blog is merely a place where I can share output from a truly marvelous bridge deal generating program that is also called Bridge, Out Ahead. For the current link to that program, see this blog post.
This user guide is for the bridge deal generating program.
If you try to use the program and it doesn’t work as described in this guide, check out this post about known browser compatibility issues.
To reach the website where the program runs, click on the link in this blog post, or cut the URL from that link and paste it into the address bar of your web browser and press ENTER. You should see this:
Are your eyes burning from the gaudy colors? I address changeable colors and themes in a separate post.
I’ll run through all the options, but first let’s generate a bridge deal without changing the setup, just to see some immediate action. Look for the row of buttons about a third of the way down the page. They look like this:
Click on the “Deal” button. The page should very quickly show you a bridge deal, like this:
I’ll give you a moment to recover from your amazement. Just take deep, calming breaths until your heart rate returns to normal.
OK, let’s learn about the options. First, though, let me tell you the whole point of this program so the options make sense. The purpose of this program is to generate bridge deals. If you know how to play bridge or if you have even just looked at the bridge column in the newspaper, you may have noticed that for each bridge deal there is a dealer and there is something called vulnerability, sometimes shortened to “VULN”. Those two things are required for every bridge deal, so we let you specify them before generating the deal. Other options on the screen have to do with how hands are evaluated, or how they appear on the page.
This program does attempt to analyze hands and suggest some bids, but it does NOT attempt to play the hands. The analysis and bidding is done because the author of this program is writing it to enhance his learning of hand evaluation and bidding. The bidding is still under development so you will see it stop abruptly in many cases. Play of the hand is a whole other matter, beyond the scope of this program. There are several good programs out there that play hands for you, or with you. This program specializes in generating deals. You can take the deals from this program and import them into other programs if you want to play the hands (more on that here and here).
Deal Type option
The “Random Deal” option will make the program generate a bridge deal with no conditions specified up front. It is as random as the computer can make it.
The “Customized Deal” option will make the program take you to the deal customization page when you press the “Deal” button. This is explained later in this guide. I will tell you now, though, that a customized deal is still random cards—it just happens to fit a configuration that you have specified. This is accomplished by generating deals randomly until the program finds one that suits your custom configuration. This could take as few as one shuffle or as many as millions.
The “Manual Deal” option will take you to a deal setup page where you can specify the exact cards to be dealt. This is explained farther on in this guide.
Number of Deals
This is a dropdown box directly under the “Deal Type” option. You can generate 1, 16, 32, 64, or 128 deals. If you generate more than one deal with a single press of the “Deal” button, you will still see just one deal on the screen; but if you save off the Analysis, LIN, or PBN files generated by this program (explained later on in this guide) then they will contain multiple deals.
Dealer option
Choose which player will be the dealer.
If you choose “Rotate” then the program will assign the dealer to your deal or deals in the order specified on the standard duplicate bridge scoresheet.
Vulnerable option
Choose which team or teams, if any, will be vulnerable.
If you choose “Rotate” then the program will assign vulnerability for each deal in the order specified on the standard duplicate bridge scoresheet.
Use Length Points option
This option does nothing at the moment. The program defaults to NOT using length points—it only uses high-card points (HCP). This reflects the fact that the author has not yet learned about length points in class, and so has taken the simple expedient of only counting HCP.
Use Dummy Points option
This option does nothing at the moment. The program defaults to NOT using dummy points. Dummy points will be implemented later.
Hands Visible After Deal option
This option lets you control whether you will see all the cards after they are dealt. The purpose and use of this option is fully explained near the bottom of this post.
Now let’s explore the buttons. You have already seen and, I hope, tried the “Deal” button, and you saw how it gave you a bridge deal and also plopped some text into the “Generated Script” area at the bottom of the screen. That all happened pretty much instantly because the “Deal Type” was set to “Random Deal” by default. But suppose you want to generate a bridge deal that has some specific characteristics. Why would you want to do that? Several reasons. First, maybe you are studying one kind of bid sequence, and you want one or more bridge deals that will be conducive to that sequence. I say “conducive to” and nothing about a guarantee because while this program does its best to generate deals to spec, people or other programs still have to actually play the deals, and they may evaluate them differently than does this program. But you get the idea: you want a deal that could possibly lead to a particular opening bid, so this program lets you customize it. Or perhaps you are an expert, but you want to play a large number of deals with a particular configuration. Or you are a bridge teacher and you need bridge deals that suit the lesson you are about to teach to your students. This program lets you generate a whole slew of suitable deals very quickly.
So, how do you generate random deals with specific characteristics? First, select the “Customized Deal” option under “Deal Type”, in the upper left of the page, like this:
Before pressing the “Deal” button you should select the number of deals you want, using the dropdown box. Here I have chosen just one deal:
Now fasten your seat belt and press the “Deal” button.
Wham! You should now see this page:
I know your emotions are running high. You’re probably feeling like little Winthrop did when he got his trumpet in “The Music Man”. It’th the moth thcrumpthiouth thing you ever thaw.
Let’s explore this page.
You will see two identical buttons that say “Click here to continue with deal”. DON’T PRESS THEM YET! I’m just pointing out that there are two of them, and that’s on purpose. This is because I had one at the bottom, but on some platforms (iPad especially) it was hard to scroll down and press it. So I put it on the page twice in hopes that users can reach one or the other. Someday I’ll address the page sizing and scrolling issues but nyot nyow.
Notice near the top you are instructed to select point ranges for everyone but the dealer. You don’t actually have to do anything if you don’t want a specific point range. Leaving them set to “Random” will work just fine:
Non-dealer player point ranges are set by clicking on the drop down next to each player. Here’s the available point ranges for the dealer’s partner:
Experienced bridge players will recognize this as a cornucopia of meaningful point ranges similar to those that come up all the time in bridge literature.
For the Left Hand Opponent and the Right Hand Opponent, clicking their drop downs will give you the same point range options as you have for the dealer’s partner.
OK, so you’ve either accepted the default “Random” point ranges or you’ve chosen the desired point ranges for three of the players. Now you get to pick one option from the rest of the page to describe the dealer’s hand (in actual practice, you would probably choose the dealer configuration—or at least have one in mind—before tweaking the other players’ point ranges). That is, if an option says “1 of a major” then it means that the dealer will have a hand that is suitable for opening a major suit at the one level. The dealer’s hand will have points somewhere within the range that is suitable for that kind of opening; the other players will have hands with points based on the point ranges you chose for them (or random, if you left them alone).
Please note that the options for the dealer’s hand are grouped logically for convenience and readability, but you only get to choose one option from this entire page (you are describing just one bridge deal at a time, after all). So don’t go trying to choose one option from each of the big boxes of options. Only the last one you click will be in effect. It’s a radio button, so you will notice that only one is ever selected at any given moment.
Once you have selected the player point ranges and the dealer’s hand configuration, now you can press the “Click here to continue with deal” button. Doing so should take you back to the first page. Here, for instance, is a customized deal generated based on the selections above, where the dealer should be able to open 1 of a major and the other three seats should have a randomly-assigned number of HCP:
WARNING: It is possible to configure a deal with player point ranges and a dealer hand configuration that is impossible to generate. A prime example is a dealer hand with 31-32 points, and partner, LHO, and RHO all with 10+ points. These all add up to over 60 points, but there are only 40 points in the deck. I will eventually prevent this kind of thing programmatically, but for now what will happen if you go ahead with this deal generation is the program will run for a very long time before giving up. How long? Long enough to try 10,000,000 random shuffles of a virtual deck of cards. It could be half an hour or more. Go ahead and close your browser tab if you don’t want to wait it out, but here’s some news: the program on the server will keep churning away on your request for the full allotted number of shuffles, so it will not respond if you try to reload it right away. I am working to deal with this situation, but in early days just try to avoid impossible configurations.
If you do submit an impossible or very rare configuration, this is what you will see, but only after the server has tried up to the maximum number of shuffles that it is set to try:
If you chose a setup that takes a long time then you may see this when you get back to the first page:
Note that no deal is displayed, and under the row of button you see the message “Please wait while your deal is finalized.” So, just wait. Buttons are disabled at this time, but don’t go nuts clicking on them. Some browsers save up those clicks and fire them off when the controls are re-enabled. Chaos ensues, and it’s on you, man. Most deals will appear instantly or within a few seconds, though, so it’s only the exotic ones that will get the “wait” message.
Eventually, you will get the customized deal or the “deal is impossible” message.
As you keep generating deals, more text will be added to the bottom of the “Generated Script” area at the bottom of the screen. This feature lets users collect not actual deals, but sets of deal configurations that someone (me) can run on a command line as a script to produce sets of deals in one file. This is described further in a separate post on requesting sets of custom deals (that is, users requesting them from me, as opposed to generating one deal at a time themselves). Update: With the recent addition of the ability for you, the website user, to generate multiple deals at once, there is less need for me to generate sets of custom deals. Feel free to ask, though. If I think you can do it yourself I’ll be glad to show you how; if it’s something more esoteric, such as a mixture of different types of deal configurations, then I will be happy to build it for you.
So you can have completely random deals, or random deals that correspond to one of many possible configurations selected by you, the user. Who could ask for anything more?
YOU! That’s who could ask for more. All that random and semi-random stuff is great, but what if you want a deal where you can specify every single card? We got you covered. Under Deal type, select the “Manual Deal” option:
Now click the “Deal” button and you will see this page:
I know: thcrumptiouth.
This page is bare bones, but therein lies its beauty. I toyed with various ways of presenting the cards and having the user click on them to deal them out, but being of a certain age I did not like all the mousing required. I hope you like typing, because that’s how you set up a manual deal on this page. Just type in “A” or “K” or “Q” or “J” or “T” or digits 2-9 in the text fields next to each suit. If you want a void suit, type only the word “VOID” into the text field of a suit.
For now, this page does no validation of what the user keys in. If you key in invalid combinations of cards (e.g. putting the same card in multiple hands) then you will either get no deal, or some random deal that I cannot predict. So you know what, don’t do that!
Let’s take it for a spin. Suppose you are intrigued by the deal at the bottom left of page 30 of the June 2022 issue of The Bridge World. You would like to study it and perhaps play it in your bridge program. Now, you could probably wander over to your bridge-playing program and enter that deal somehow. But let’s assume you have reasons for wanting to use my program to generate it (I assure you, there are such reasons which I will get to in a moment). On the main page of my program, choose the Manual Deal type, and set the dealer to “East” and vulnerability to “Both” as specified in the magazine:
Press the “Deal” button to get to the manual deal setup screen. There, key in the deal from page 30 like this:
Now press either of the “Click here to continue with deal” buttons and you will see this:
Boom, there it is. You can see the deal in all its glory. Also, notice that in the script text area at the bottom of the screen you see a script that someone (I, for instance) could run on a computer with my bridge program installed, to recreate this deal. This is useful for me because while I often study deals exactly as specified, I like to also study them with different combinations of dealer and vulnerability. So I often set up scripts to generate 16 variations of one deal of the cards. While the one-off creation of a manual deal might be something you would rather do in your bridge-playing program, I like to use my program so that I can save off scripts and add to them or modify them to generate multiple versions of the same deal. I can then take the output from running that script (e.g. sixteen variations on a deal) and load that into BBO and play it every which way.
But wait…there’s more!
When you study deals in a book or magazine or online, quite often the writer will specify only some of the cards. The purpose of that is to present the reader with a scenario and let them think through how they would bid it. Only later do they reveal all the cards. When I study such analysis, I do like to use my imagination but I also think it would be very useful to be able to actually see and play out the specific cards against randomly-dealt opponent hands, and see how results for my specific cards vary versus one or more other combinations. So for instance, the deal on page 30 of The Bridge World actually first appears on page 24 of the same issue, but only North and South are specified. Let’s try that on the manual deal setup page. Note that I leave East and West completely blank:
After pressing “Click here to continue with deal” I see this:
While North and South are exactly as specified, East and West were randomly dealt by the program. If you press “Deal” again you will be taken back to the manual deal setup page, and the cards you keyed in will still be there. If you then press “Click here…” again you will get another deal with the same North and South but with a brand new East and West. And so on, as many times as you like. Each time you do this, if you intend to load the resulting deal into another program, be sure to save off the PBN or LIN file that is produced for each deal. The whole process of saving and using deals is described later in this guide.
As you might have guessed…there’s more! Many problems are presented not only as partial deals, but as partial deals but with specific shapes. This is usually done in writing by specifying “x” as a placeholder for an unnamed card. So a suit might be shown as “AJxxx”. Wouldn’t it be nice to be able to set up deals using that notation, and letting the system plug in cards in place of the exes? We got that covered. Let’s take our same deal, but let’s change it so North and South are only partially specified but they have some placeholders, and the shape of East and West are completely defined by placeholders. Like this:
Note that due to the lack of input validation, the user is responsible for keying in the correct number of placeholders. If you key in too many you probably won’t break the program, but you will get unpredictable results—a valid deal but not the deal you expected. If you key in too few exes, well, there is no such thing. Notice that in the previous example where we left East and West blank there were no placeholders at all. The program works by first filling in specific cards, then by randomly assigning cards to placeholders; if there are any undealt cards after that, it distributes them randomly. So be as specific as you want or need to be and the program will handle the rest. OK, now here’s what you get the first time you use the placeholders as shown above:
Quite a bit different from the actual deal, isn’t it? If you are like me, you often read analyses that go on about how a deal would come out differently if opponents cards are onside or offside in various ways. That’s great, and it is a good mental exercise to try to visualize it. But now you can also quickly see and even play any number of variations with random or specific shapes, thanks to placeholders.
Finally, there may be times when you want to specify either specific cards, or placeholders, or both for a suit in a hand, and rather than those being the minimum number of cards dealt you want it to be the only cards dealt—in other words, if there are any cards left over after all specific cards and all placeholders have been dealt out, you don’t want any random cards landing in a suit for a hand. To do this, key “B” in the suit text box after any specific cards and “X” placeholders. Actually, you can key the “B” anywhere in the text box, but if you key a “B” before a specific card or an “X” then results are unpredictable (which in Progammerese language means “bad”). So just use it to say what you mean. For instance, if you wanted North to have some specific cards and two random cards and nothing else, you would do this:
And the resulting deal has only four spades in North:
You may have noticed that on the line with the “Deal” button there’s another button that lets you get deals a different way. Here’s another look at it:
The “Browse” button lets you load deals from a file in PBN or LIN format. The complete explanation of that feature is in a separate blog post.
That’s it for generating deals. But there are additional buttons that let you do things with the generated deals. They are located underneath the row with the “Deal” and “Browse” buttons:
These buttons will generate some kind of file for you to view or save to your computer. The buttons work differently on each platform, so I am only going to describe how they work on my Firefox browser running on Mac OS. The difference on other platforms depend on how your browser handles it when the user clicks on a link to a document that is eligible for viewing or saving as a file. Each browser seems to do it slightly differently, and some even make it hard to tell that anything happened at all. But Firefox on Mac does it in an obvious and flexible manner, so here we go.
Analysis button
The program analyzes the deal and performs some analysis of each hand—things like shape, HCP, quick tricks. It then writes a step-by-step narrative of the auction. This is based entirely on the bidding logic as I implemented it, and is not necessarily correct. Also, it conforms closely to my interpretation of the class that I was taking as I wrote this program. Later on I may make it possible to plug in different point systems and conventions, but that is beyond the scope of this program right now. The main point is that you should take my analysis with a grain of salt.
If you want to see, save or print the analysis, press this button. On Firefox on Mac OS you will see a pop-up like this:
PBN button
The program produces a Portable Bridge Notation file of the deal or deals, suitable for loading into programs that let you import your own file. The PBN file does not include the auction or the play of the hand—just the details needed for people or other programs to actually play the hand.
Pressing this button will get you a pop-up just like the one you got with the “Analysis” button, but with a different file name.
Here’s how to load the resulting file into one program that supports PBN format.
LIN button
The program produces a LIN file of the deal or deals, suitable for loading into programs that let you import your own files. The LIN format is used by bridgebase.com.
Pressing this button will get you a pop-up just like the one you got with the “Analysis” button, but with a different file name.
Here’s how to load the resulting file into bridgebase.com.
Script button
The program produces a script suitable for someone (me) running on the command-line of a system where the bridge deal generating software is installed. It writes a line of generation code for each deal that the user generates between the time the website is first brought up on their computer, and the next time they refresh the page. So for instance, if you generate ten deals with configurations that interest you, you can press the “Script” button to capture a file containing the script to produce ten more deals with that same configuration. The deals that result from running the script will not be identical to the deals you generated on the site, since the script only saves the configurations, not the actual hands that are dealt. If you want to save actual deals, you have to save PBN or LIN files individually after each deal. Update: If you used the Manual Deal option and you specified every card in the deal exactly, then your script will reflect that and running the script will in fact generate the same deals every time. It is only when your deals involve two or more randomly-assigned cards that the deals will change when I run your saved script.
If you have generated some deals but you don’t care for the configurations and you want to start over, just refresh the page in your browser and it will wipe out the accumulated script.
Pressing the “Script” button will get you a pop-up like this:
Details for requests for custom sets of deals are covered in another post on this blog.
Other functionality.
Hide the hands.
This program is mostly for generating deals and capturing analysis, files, and scripts. However, early on I envisioned it as a learning tool for the user. Other programs are better for that purpose, and you can easily load hands from this program into them (I’ll show you how in another post). However, you can still use this program for some bridge exercises.
When training yourself to analyze your hand, it is useful to see only your hand; otherwise, your awareness of your partner’s or your opponents’ hands will influence your thinking about how you would bid. I therefore made it possible to generate deals but to hide all the cards at first. You specify visible cards by choosing “Yes” for the Hands Visible After Deal Option. You make this selection before pressing the “Deal” button. It only affects the cards after the next deal is performed—it does not affect visibility of any cards that might already be on the page from a previous deal:
You have already seen the result of the “Yes” option because it was selected for the first screen sample, and you could see the resulting cards after the deal was generated.
If you choose “No” before the deal then the cards will be hidden after the deal is generated. Here’s a page where I chose “No” for hands visibility then pressed “Deal”. There is a “Deal generated…” message above the deal area, but you don’t see the cards:
Now if you want to think about how you, as North, would bid this hand, just click anywhere in the area where North’s cards would appear, and the hand will be revealed:
You can selectively view or hide each hand by clicking on it. For instance, you might imagine how you would bid North’s hand, then you might reveal South’s hand and imagine how South would respond. Now reveal East and West and imagine how they would have interfered with your clever plan. As I wrote before, other programs that have robot bidding or that let you play out the hands with other people are better for this sort of thing, but you can get in some quick practice on hand analysis with this program.
Change the theme/style of the page.
See the little hot dog cartoon? Click on it (not here, but over where you have the actual page open in your browser). If the page loses its styling and looks like an utter mess, click on whatever the next image is in that spot, and keep clicking until the little hot dog (and the styling) comes back. Your system doesn’t support style swapping in the way that I have implemented it.
But if you are on Firefox on Mac OS, for instance, not only will the cartoon change to some other image, but the style of the page will change to match the subject of the image. It’s really neat. I’ll do a separate post on the themes (edit: I did it), and maybe someday I’ll learn how to make theme/style switching work for everyone.
Wrapping Up
If you have questions that are not answered by this guide, feel free to contact me through the blog.