Usage
seed_deal number
Command Line: -s
$ deal -s number ...
Summary
seed_deal is used to seed the random number generator, to make sure that Deal generates the same sequence of
random numbers.
Care has to be taken if you want to make sure that you are generating the same sequence of deals. For one thing, if you have a main inner loop, you should add the command "finish_deal" to the main section.
main {
finish_deal
...
}
That bypasses some optimizations and forces an entire deal to be generated each time through main.
Command: deal_deck
Usage
deal_deck
Summary
deal_deck is called at every new deal,
even when all 52 cards are specified (stacked) precisely.
Imagine stacking cards as stacking them in an undealt deck,
but that the cards are only distributed to the hands when
deal_deck is called.
Most of the time, you won't need to call deal_deck directly, but it is
useful to understand its behavior if you are going to write advanced
procedures like input formats.
Stacked cards are permanently stacked until the deck is reset. In this code:
stack_hand south {AKQ32 AJ53 K54 2}
deal_deck
deal_deck
puts [south spades]
The output is "AKQ32". Use reset_deck
to undo card stackings.
The deal_deck procedure does one thing rather complicated
when it is called, the first thing it does is execute all
code registered with the
deal_reset_cmds.
This allows the script writer to do one of several things before
the deal is generated:
- Delete metadata related to the deal. For example, the first time
the user calls
deal::tricks south spades it calls the
double-dummy processor. Each time after that, it uses a stored
value for this function call up until the next call to
deal_deck.
- The reset command might, instead, read the next deal from a file,
stack the deck, and then re-register itself. Then when deal_deck is
is called, it just deals that hand from the file. This is a crude
way of allowing Deal to transparently read deals from a file (or generate
deals in other ways, such as smart stacking.
|
| For Programmers
- Implementation:
- C
- Location:
tcl_deal.c, function tcl_deal_deck
|
|
Command: reset_deck
Usage
reset_deck
Summary
This forgets about all stacked cards. The deck, from Deal's
point of view, plus a list of cards which must go to specific hands.
The cards which are assigned to specific hands are "stacked." The cards
which are not stacked can go anywhere at the next call to
deal_deck.
|
| For Programmers
- Implementation:
- C
- Location:
tcl_deal.c, function tcl_reset_deck
|
|
Commands: stack_hand and stack_cards
Usage
stack_hand handname hand
stack_cards handname suitname holding [...]
Summary
By default, these two routines just call
deck_stack_hand and deck_stack_cards,
respectively - that is, they forcibly place cards in the deck.
But these routines are meant to be overridden. For example, when using
one of the input formats which reads deals from a file,
the format will redefine these two procedures to give errors.
% deal -I "line foo.txt" -e "stack_cards south spades AJ"
Tcl stack dump of error info:
No card stacking with input format ::line
...
A more complicated re-definition occurs in the
smartstack input format, which alters its hand
generation depending on what cards are stacked where.
|
| For Programmers
- Location:
hand.c, function tcl_stack_hand and
tcl_stack_cards
|
|
Commands: deck_stack_hand and deck_stack_cards
Usage
deck_stack_hand handname hand
deck_stack_cards handname suitname holding [...]
Summary
These routines are the "underlying" deck-stacking routines. Any cards
stacked with these routines remain stacked until the next call to
reset_deck
|
| For Programmers
- Location:
hand.c, function tcl_stack_hand and
tcl_stack_cards
|
|
Command: stacked
Usage
stacked handname
Summary
Determines what cards are stacked to this hand, returning them as
a list of holdings:
south gets AS KH 3H QD JD TC 9C 8C
puts [stacked south]
writes out the list:
A K3 QJ T98
This is useful for the smartstacker, because
we don't want to force the user to stack cards *after* specifying conditions.
stack_hand north {AJT KT3 KJ 75432}
deal::input smartstack south balanced hcp 20 21
The call to stack_hand occurs before smartstack
is loaded, so stack_hand has not been redefined. So what
smartstack does is read the cards already stacked, and
use that for its initial conditions.
|
| For Programmers
- Implementation:
-
- Location:
tcl_deal.c, function tcl_stacked_cards
|
|
Command: deal::nostacking
Usage
::deal::nostacking
Summary
This procedure redefines the stack_hand and
stack_cards procedures to generate error messages, and
generates an error if any cards are currently stacked.
This is used in all of the input formats which read complete deals from
files, and thus are incompatible with stacking.
|
| For Programmers
- Implementation:
-
- Location:
deal.tcl, function deal::nostacking
|
|
Command: deal_reset_cmds
Usage
deal_reset_cmds {...code...} [ ... ]
Summary
This adds a set of commands that are to be called before the next
deal. The code is executed at the next call to the
deal_deck procedure, which, unless
you are doing something complicated, means it is called at the beginning
of each time through the evaluation loop.
deal_reset_cmds can be used so that metadata about the previous deal,
such as cached values and the like, are unset. See
deal::metadata.
It is also used for defining input formats,
so that deals can be read from files. For example, the "line" input format
has the following routine declared:
namespace eval line {
#....
proc next {} {
variable handle
set length -1
catch { set length [gets $handle line] }
# ... process the line, or handle oef stuff ...
# ...
deal_reset_cmds {::line::next}
}
}
The key is that when line::next is done, it re-registers itself, making
sure that it is called next time through as well.
The code passed in to deal_reset_cmds is
called only once, at the next request for a deal - think of it as
registering a one-time trigger. Multiple triggers can be registered -
they are called in the reverse order that they are added, which can seem
counter-intuitive until you think of the process as an "undo" process.
|
| For Programmers
- Implementation:
-
- Location:
tcl_deal.c, function add_reset_cmds
|
|
Command: deal::metadata
Usage
deal::metadata name {...code...}
Summary
Currently, this is just a peculiar way of caching slow evaluation routines.
At the moment, the only place it is used is in
deal::tricks.
When you call deal::metadata, it will check to see if
there is a value associated with the name requested
already. If there is, the value is returned. If it does not, it evaluates the
specified code and associates the result with the name. The key
is, when the next deal is being analyzed, all the cached values are pitched.
This isn't really necessary or efficient in most cases, but with
evaluations which take some time, e.g. GIB calls, it
improves things.
|
| For Programmers
- Implementation:
Tcl
- Location:
deal.tcl
In later releases, metadata read from input streams (say, the fields
from a PBN file) will also be stored here.
This procedure uses
deal_reset_cmds.
The metadata is cleared each time the deal_deck
command is called.
|
|
Input formats
Command: deal::input
Usage
deal::input formatName args
Summary
The deal::input command is used to define an input source
for deals. It works as follows:
- The file
input/<formatName>.tcl is loaded. This
Tcl file should define a new Tcl 'namespace' with the name formatName,
with member procedures named set_input and next.
- Deal then calls
<formatName>::set_input args, which should
initialize the format reading. Usually, the argument(s) are one argument
representing the source file.
- The next deal,
<formatName>::next is called.
|
For Programmers:
- Implementation:
- Tcl code
- Location:
- deal.tcl
| |
Input Format: giblib
Usage
deal::input giblib [filename]
or on the command line:
% deal -I giblib
or
% deal -I "giblib filename"
Summary
Specifies that deals are read from the specified file in the format
of Matt Ginsberg's library.dat file. This includes double-dummy tricks
data, so that later calls to deal::tricks
will not entail calls to the GIB binaries.
If no filename is given, the library tries to read from a file called
"library.dat" in the current directory.
The -I command-line flag is a quick alias for
deal::input, passing the next argument as
Tcl arguments to the deal::input command.
|
For Programmers:
- Implementation:
- Tcl code
- Location:
- input/giblib.tcl
This procedure uses deal_reset_cmds.
|
|
Input Format: line
Usage
deal::input line [filename]
Summary
Specifies that deals are read from the specified file in the format
written by Deal's "-l" option.
If no filename is given, the library reads from standard
input. This way, you can create a single data file and then
run several different queries against it:
% deal -l 100000 > sample
% deal -e "deal::input line sample" -i query1
% deal -e "deal::input line sample" -i query2
[ The -e option just evaluates the code in the next
argument as Tcl code. Alternative, you can use the -I
option, which is shorthand for input formats:
% deal -I "line sample" -i query1
The -I args option is exactly the same as -e "deal::input args"
|
For Programmers:
- Implementation:
- Tcl code
- Location:
- input/line.tcl
|
|
Input Format: ddline
Usage
deal::input line [filename]
Summary
Specifies that deals are read from the specified file in the format
written by Deal's ddline format.
The ddline format include doubled-dummy tricks data, so when using ddline for input, calls to deal::tricks return the data read from the file.
|
For Programmers:
- Implementation:
- Tcl code
- Location:
- input/line.tcl
|
|
Input: smartstack
Usage
deal::input smartstack hand shapeclass [holdproc min max]
or on the command line:
% deal -I "smartstack shapeclass ..."
Summary
This is the most complicated Deal input method in the current release.
It does not read deals from a file - it is, instead, a different path to
generation of deals. The purpose of this format is to allow fast generations
of deals where one hand fits a very specific description. For example,
if you want to find hands where south has a balanced 27-count, you
could write:
deal::input smartstack south balanced hcp 27 27
On my computer, that returns the first deal in 14 seconds, and every deal after
that takes a tiny fraction of a second. That's because smartstack
first builds a large "factory" in memory, but once it is built, the
factory spits out hands matching this condition very quickly.
By contrast, a standard "deal" script to find balanced 27-counts
takes about 2.8 seconds to find each deal. That means that if you only
want to find about five deals of this sort, the old style program
is faster, but if you want a lot more, use smartstack.
For example, if you wanted 1000 examples, smartstack
takes about 15 seconds, while the old deal will take about 45 minutes.
One interesting feature of smartstack is that it is often
faster if the hand type is less frequent. For example, it takes about 6
seconds to find ten deals with 9-card spade suits, and about 5 seconds to
find ten deals with 10-card spade suits. Similarly, it is faster at
finding hands with exactly 9 controls than it is at finding hands
with 9-12 controls.
The smartstack routine only works on one hand - after it
places cards in that hand, it generates the rest using the usual
algorithm.
|
For Programmers:
- Implementation:
- Tcl code
- Location:
- input/smartstack.tcl, lib/handFactory.tcl
- Notes
- See the two articles from the bridge developers mailing list
describing the algorithm:
My first stab at describing it and
some corrections.
|
|
Formatting
Command: write_deal
Usage
write_deal
Summary
This is the the name of a procedure which is called when deals are accepted.
By default, it writes the result in the format:
S: 98632
H: A4
D: AJ754
C: J
S: K S: AJT7
H: J3 H: QT95
D: T98 D: Q2
C: AKT7532 C: 984
S: Q54
H: K8762
D: K63
C: Q6
--------------------------
New output formats are defined by redefining this routine.
|
| For Programmers
- Implementation:
- Tcl
- Location:
format/default
|
|
Command: flush_deal
Usage
flush_deal
Summary
This routine is called at the very end of a run for deal. It does nothing,
by default, but some output formats may require it if data is cached.
|
| For Programmers
- Implementation:
-
- Location:
YYYYY, function ZZZZ
|
|
Output Format: format/par
Usage
source format/par
Summary
By including this file, you are setting the output format to write the results in PBN format, with results set to the double dummy theoretical par.
$ deal -i format/par 1
[Date "2008.05.19"]
[Board "1"]
[West "West"]
[North "North"]
[East "East"]
[South "South"]
[Dealer "N"]
[Vulnerable "None"]
[Deal "N:K.A7.QJT9865.AK7 T94.K98532.2.943 A872.QT4.AK4.862 QJ653.J6.73.QJT5"]
[Contract "6N"]
[Declarer "S"]
[Result "12"]
[Score "NS 990"]
{
S: K
H: A7
D: QJT9865
C: AK7
S: QJ653 S: T94
H: J6 H: K98532
D: 73 D: 2
C: QJT5 C: 943
S: A872
H: QT4
D: AK4
C: 862
north makes 9 tricks in clubs
north makes 12 tricks in diamonds
north makes 8 tricks in hearts
north makes 7 tricks in spades
north makes 12 tricks in notrump
east makes 3 tricks in clubs
east makes 1 tricks in diamonds
east makes 5 tricks in hearts
east makes 4 tricks in spades
east makes 1 tricks in notrump
south makes 8 tricks in clubs
south makes 12 tricks in diamonds
south makes 8 tricks in hearts
south makes 7 tricks in spades
south makes 12 tricks in notrump
west makes 3 tricks in clubs
west makes 1 tricks in diamonds
west makes 5 tricks in hearts
west makes 4 tricks in spades
west makes 1 tricks in notrump
}
[Auction "N"]
Pass Pass 6N
[Play "W"]
*
|
| For Programmers
- Implementation:
- TclLocation:
format/par
|
|
Output Format: format/ddline
Usage
source format/ddline
Summary
By including this file, you are redefining the output format to the form "ddline", which writes out the deal on a single line, as with the '-l' flag, but then adds complete double-dummy data to the deal as well. If you write the output to a file:
$ deal -i format/ddline 100 > doubledummy.txt
then you can use the ddline input format to read the file back in:
$ deal -I "ddline doubledummy.txt" -i query.tcl 100
And any call to deal::tricks in query.tcl will use the value stored doubledummy.txt.
|
| For Programmers
- Implementation:
- TclLocation:
format/ddline
|
|
|