Back to Deal Top Page
Plane Dealing image

Deal 3.0

An Advanced User Guide

Covering:
  • Vector additive functions
  • Shape functions
  • Customizable output formats
  • Statistical analysis
  • Hints for fast scripts

Prologue

First things first, you will need to download Deal and build it. The rest of this guide assumes you have already done this.

This guide also assumes you know everything in the Introductory Tutorial. Some sections in this guide will require more knowledge of Tcl than others.

**Warning** It takes careful eyes, at least on the version of Netscape I am using, to distinguish between normal parentheses, (), and curly parentheses, {}. Almost all of the paretheses in the script listings below are curly parentheses.

Contents

Vector additive functions

In the Introductory Tutorial, we mentioned three functions which we called "additive functions." They were hcp, controls, and losers. We called them additive because we could compute them for a single suit holding in a hand or across the entire hand by summing over all the suits.

In this section, we will show how a user can create a large class of fast additive functions, and show how they can be used.

The most common additive function is hcp. How is it computed? Given a suit holding, we count 4 for the ace, 3 for the king, 2 for the queen, and 1 for the jack. Here is how we would define this with a "vector": 

defvector Hcp 4 3 2 1
That's pretty simply. Similarly, we can define a Controls vector: 
defvector Controls 2 1

Once these vectors are defined, we can use them as functions anywhere we used hcp and controls.

Now, considering the following case: Your partner, north, opens a weak two spades, and you have the agreement that partner always has a 6-card suit with at least two of the top three honors. You can define a vector: 

defvector Top3 1 1 1
Now, to test the quality of the spade suit, you could say: 
if {[Top3 north spades]>=2} { ... }
Pretty simple.

So you decide to write a "weak2" procedure: 

defvector Top3 1 1 1

proc weak2 {hand suit} {
  if {[$suit $hand]==6 && [Top3 $hand $suit]>=2} { return 1 }
  return 0
}
You can call this by saying: 
#... 
main {
	if {[weak2 north spades]} { accept }
}
This will deal out hands where north has exactly six spades and two of the top three spades.

This works okay (although you have forgotten to restrict the other suit lengths, so you could end up with voids and side 5-card or 6-card suits.)

Two weeks later, you and your partner decide that you will also consider a suit worth a weak 2 if it contains three of the top five cards, which, specifically, really means you've now allowed suits led by QJT, KJT, and AJT. This is not an uncommon agreement.

We could, of course, write a routine called "Top5" and check both Top3 and Top5, but a little cleverness allows us to roll this all up into one vector. 

defvector weak2quality 2 2 2 1 1
You will see, if you think about it, that this vector evaluates to 4 or more precisely when the suit has the right quality for a weak two. You then rewrite the weak2 function: 

defvector weak2quality 2 2 2 1 1

proc weak2 {hand suit} {
  if {[$suit $hand]==6 && [weak2quality $hand $suit]>=4} { return 1 }
  return 0
}
The advantage of the vector functions is that they can be computed quickly, using table lookups.

However, vectors don't compute many additive functions, like "losers" and "quick tricks," or even high card points with distribution adjustments. For this, you will need to use the Deal 3.0 feature, holding functions. It pretty much covers *all* such procedures, but still allows for a fast lookup.

Shape functions and classes

In the Introductory Tutorial, we mentioned the two functions, balanced, and semi_balance, and called them "shape functions" because they take a hand name as an argument, the return value depends only on the "shape" of the hand - that is, on how many cards are in each suit.

In fact, balanced and semi_balanced are a special sort of shape function, which we will call a "shape class." A "shape class" is a shape function which returns only the values 0 and 1, and therefore defines a class of shapes, namely those shapes which evaluate as 1.

Deal allows for extremely fast shape class and shape function computations.

A basic shape class

For example, lets say that we want to write a shapeclass which returns 1 if our hand is right shape for a one spade opening. We would do so with the following definition: 
shapeclass spadeshape {
    if {$s>=5 && $s>=$h && $s>=$d && $s>=$c} { return 1}
    return 0
}
This defines a routine, spadeshape, which returns true precisely when the hand has 5 or more spades and at least as many spades as any other suit.

Notice, the variables $s, $h, $d, and $c. Consider it this way - when you pass a hand name to a shape function, it sets these variables to the suit lengths, and then evaluates the code. [ That is not how it works in reality, because that would be too slow. ]

The idiom, if {expr} {return 1} return 0 is so common in shape classes, Deal has a shorthand, shapecond, and we could have defined spadeshape as: 

shapecond spadeshape {$s>=5 && $s>=$h && $s>=$d && $s>=$c}

A sample shape function

Shape functions can return any string. They can be extremely powerful.

For example, we can define a function, opening_suit: 

shapefunc opening_suit {
	if {$c>$s && $c>$h && $c>$d} { return clubs }
	if {$d>$s && $d>$h && $d>$c} { return diamonds }
	if {$s>=5 && $s>=$h} { return spades }
	if {$h>=5} { return hearts }
	if {$d>=5 && $d>=$c} { return diamonds }
	if {$d>$c} { return diamonds }
	return clubs
}
This function returns the name of the suit in which you should open open the hand (at least according to some people) in Standard American bidding.

Recently, a number of people have mentioned to me Bergen's "rule of 20" for determining whether a hand is worth an opening bid. According to the rule, add your high card points to the sum of the lengths of your longest two suits. If that adds up to 20, open the hand. We can write this as follows: 

shapefunc bergen::shapeval {
    set p [lsort -integer -decreasing "$s $h $d $c"]
    set first [lindex "$p" 0]
    set second [lindex "$p" 1]
    expr $first+$second
}

proc bergen::opening {hand} {
    expr { [hcp $hand] + [bergen::shapeval $hand] >= 20}
}
We can now use Bergen's rule in our simulations.

Calling shape functions explicitly

A shape function (or shape class) can be called with 4 numeric arguments: 
set open3343 [openingsuit eval 3 3 4 3]
This is most useful in defining shape classes and functions from other shape classes and functions. Assume you have shape classes spadeshape and heartshape and you want to define a new shape class, majorshape. You can do so as follows: 
shapecond majorshape \
	{[spadeshape eval $s $h $d $c] || [heartshape eval $s $h $d $c]}

Customizable output formats

With verson 2.0 of Deal, it is finally possible to write your own customizable format routines.

It is really fairly simple. When Deal accepts a hand, it calls the procedure named write_deal. When it is finished dealing the number of hands requested, it calls a procedure named flush_deal.

To change the output format, we simply redefine these procedures. Tcl does not mind such redefinitions.

For example, the formatter, format/none, is just the code: 

proc write_deal {} {
	# empty function
}
By default, the flush_deal procedure is already empty, so we do not have to redefine it here.

Why might we need flush_deal at all? Some formatters only write to output periodically. For example, format/practice writes files out.north, out.east, out.south, and out.west. The output in out.north looks like: 

                              north hands
============================================================================
     *1*                 *2*                 *3*                 *4*
  S 84                S T7                S QT3               S AJ9654
  H J8642             H Q65               H Q983              H K8
  D Q843              D KJ42              D 865               D J
  C 73                C T842              C AJ9               C K532

=============================================================================
Clearly, therefore, write_deal is buffering output internally and only printing every fourth hand. What happens when the user requests 10 deals? write_deal will be called on the tenth deal, but because the deal number is not a multiple of four, write_deal will not know to print the output. The last two hands will be lost.

The solution is to make Deal call flush_deal on completion of dealing.

A most basic formatter - printing one hand

Here is a new formatter, which we will place in a file call NorthFmt. 
proc write_deal {} {
	puts "S: [north -void --- spades]"
	puts "H: [north -void --- hearts]"
	puts "D: [north -void --- diamonds]"
	puts "C: [north -void --- clubs]"
	puts "============================="
}
Okay, what does this expression, [north -void --- spades], do? The expression [north spades] returns the spade holding of the north hand in a simple string form. If the suit is void, it returns the empty string. The "-void ---" in the example above tells the formatter to use the string "---" for voids.

We could do this a little more easily: 

proc write_deal {} {
    foreach char {S H D C} suit {spades hearts diamonds clubs} {
	puts "$char: [north -void --- $suit]"
    }
    puts "============================="
}
This uses the interesting feature of the Tcl foreach which lets two variables move through two lists.

The north routine, without arguments, returns all four suits, in a Tcl list format. Here is a simple formatter for the north and south hands: 

proc write_deal {} {
    puts "{[north]} {[south]}"
}
Yielding ugly output like: 
{{J9654} {KQT832} {} {42}} {{7} {A74} {T763} {J9865}}
{{KT852} {Q} {KT83} {A83}} {{96} {AK7543} {Q96} {52}}
Not pretty, but useful if piping to another Tcl program, because Tcl programs will find this fairly easy to parse.

String boxes

For more complicated formats, I have added to Tcl an invention of my own for string "drawings." Tcl does not have any decent formatting routines, other than the format command, which is based on the printf class of functions in C. I've always found printf a pain, even back in Fortran.

So I invented "string boxes." A string box is a like a drawable canvas, but for characters rather than pixels. For example, here is a slightly simpler version of the file format/okb: 

stringbox okbox 14 70
okbox write 4 15 "West"
okbox write 4 50 "East"
okbox write 0 30 "North"
okbox write 10 30 "South"
	...
This code creates a string box named okbox with 14 rows of 70 columns of text (initially all blank), and then writes the words "West", "East", "North", and "South" in different locations in that box.

Next we define the sub-boxes, one for each hand: 

	...
okbox subbox okbox.north 0 36 4 15
okbox subbox okbox.south 10 36 4 15
okbox subbox okbox.east 5 50 4 15
okbox subbox okbox.west 5 15 4 15
	...
A "subbox" is created from a parent box, and has both a row and column location, and a row and column width. In the above instance, all of our sub-boxes are 4 rows and 15 columns, and placed in the location where the hands will eventually be printed.

Our write_deal procedure would look like: 

proc write_deal {} {
  foreach hand {west south north east} {
    okputhand $hand
  }

  puts "[okbox]"
  puts "                       -----------------------------"
}

proc okputhand {hand} {

  okbox.$hand clear

  set rowhand 0
  foreach char {S H D C} suit {spades hearts diamonds clubs} {
    okbox.$hand write $rowhand 0 "$char [$hand -void --- $suit]"
    incr rowhand
  }
}
write_deal just calls the routine okputhand for each hand, then writes out the contents of the entire string box, okbox, followed by the seperator string of hyphens. Note that we convert a string box to a normal string just by using its name alone, without arguments, as in [okbox]. We can also convert a string with trailing whitespace removed from lines, by saying [okbox compact]. In fact, we probably should have used the compact modifier, since there is so much trailing white space in this format.

The okputhand procedure first clears the sub-box associated that hand, then writes out the contents of the hand one suit at a time to that same sub-box.

The output looks like: 

                              North S KT6                             
                                    H J97                             
                                    D T8543                           
                                    C T5                              
               West                               East                
               S J75                              S Q983              
               H T86                              H A52               
               D AKJ7                             D Q9                
               C AQ8                              C KJ64              
                                                                      
                              South S A42                             
                                    H KQ43                            
                                    D 62                              
                                    C 9732                            
-----------------------------
I have yet to put together complete documentation for string boxes, but I intend to do so. They have some remarkable features, and perhaps some surprises for the unwary.

Statistical analysis

Go here.

Hints for fast scripts

Documentation not yet written.
Silhouette Thomas Andrews (deal@thomasoandrews.com) Copyright 1996-2005. Deal is covered by the GNU General Public License.

Plane Dealing graphic above created using POV-Ray.