Main Guide 7A14 by Richard Pavlicek

Binary File Formats

Working with large amounts of bridge data is impractical in a text format, so I have designed various binary file formats to fit my needs. These are explained here, so that others might benefit from the structures and accumulated data.

ZBS ZBD ZDD ZRD ZRJ BIN
All binary formats follow the Intel “little endian” architecture, wherein multi-byte values are stored least significant byte first. Bits are numbered from zero (least significant) upward to the end of each record.

Provided in the documentation of each binary file is a checksum, which is simply an addition of all 32-bit words to produce a 64-bit sum (shown in hexadecimal). This can be used to verify the integrity of the file. In the event of a mismatch, the file is corrupt; try downloading again, and if it still doesn’t match, please contact me.

My Bridge File Converter will convert ZBS, ZBD and ZRD files to any other format, provided the output file does not exceed 2 GB and you have enough disk space to store it — or enough trees if the output is to a printer. For practical purposes, however, conversion of large binary files to readable formats should be limited to a small portion at a time.

Top Main

ZBS Format

ZBS (binary suit) is a way to store any suit layout, including unused cards, in the minimal space. I designed this circa 1988 for my now extinct Bridge Tutor program, because it allowed any bridge diagram (full deal, ending, paired hands, card combination, etc.) to be stored efficiently. (In those days of low memory and floppy disks, saving bytes was crucial.)

Each card can be in one of five places: West, North, East, South or unused. In a bit-mapping scheme this would require three bits per card (39 total bits) which is wasteful. Much better is a power-of-five algorithm, where the location of each card is shown by a 13-digit number in base five (each digit 0-4). The rightmost digit shows which hand (1-4) holds the ace, or 0 = unused; the next digit locates the king, etc., thru the leftmost digit to locate the two.* Conveniently, 5 to the 13th power = 1,220,703,125 (48C27395 hexadecimal) which stores in 31 bits, or 4 bytes with 1 bit left over. I use the extra bit as a flag to mean the next record belongs to the same deal, hence 32-bit records can stand alone to define a suit layout, or combine to form a diagram.

*Originally I used the reverse order (ace leftmost, two rightmost) but switched so that decoding extracts cards in ranking order (ace, king, queen) to facilitate and speed up some routines.

Encoding and decoding is straightforward. To encode, start with the two and its location (0-4); multiply by five and add the three location (0-4); multiply by five and add the four location (0-4), etc. To decode, just divide successively by five; the first remainder locates the ace; the next locates the king, etc. The record structure is shown below.

Bit Value Coding
0 Flag 0 = end of group; 1 = next record same group
1-31 Locator 0 to 1220703124

Bit	Value	Coding
0	Flag	0 = end of group; 1 = next record same group
1-31	Locator	0 to 1220703124

When records are combined, suits must be given in ranking order: spades, hearts, diamonds, clubs. For stand-alone records (single-suit layouts) suit identity doesn’t matter (at least for my purposes) but spades is assumed.

A null record (all cards unused and "end of group") would have no purpose to be included, so this fact can be used to terminate a list records, thus allowing end detection.

Top Main

ZBD Format

ZBD (binary deal) is a simple, compact way to store a complete deal. Each card must be in one of four places (West, North, East or South) so two bits of information are required for each card. Two × 52 = 104 bits, so each deal requires 13 bytes.* The bitmap of each record is shown below.

Bit Value Coding
0-1 A 0 = West; 1 = North; 2 = East; 3 = South
2-3 K 0 = West; 1 = North; 2 = East; 3 = South
4-103 … likewise in order for Q-2 A-2 A-2 A-2

Bit	Value	Coding
0-1	A	0 = West; 1 = North; 2 = East; 3 = South
2-3	K	0 = West; 1 = North; 2 = East; 3 = South
4-103	… likewise in order for Q-2 A-2 A-2 A-2

*In theory only 12 bytes are required per deal using my algorithm for Mapping Bridge Deals, but this requires significant overhead to code and decode each deal — hardly worth the effort to save a single byte. Simplicity rules.

A record starting with 32 null bits is impossible (it would mean the first 16 cards go to West) so this fact can be used to terminate any list of records, thus allowing end detection.

Top Main

ZDD Format

ZDD is a simple, compact way to store double-dummy results for each hand in each strain. I designed this for my database of 10,485,760 Random Solved Deals, a project that took almost two years of computer time to complete. The random deals themselves are not stored but generated on-the-fly (mother-of-all algorithm). Given a fixed seed, the same sequence of deals is reproduced.

Each record is 10 bytes (80 bits). Each of the 20 results (5 strains × 4 hands) is stored as a nibble, or 4-bit value. The bitmap of each record is shown below.

Bit Value Coding
0-3 NT by West 0-13 (or 15 = unknown)
4-7 NT by North 0-13 (or 15 = unknown)
8-11 NT by East 0-13 (or 15 = unknown)
12-15 NT by South 0-13 (or 15 = unknown)
16-79 … likewise in order for

Bit	Value	Coding
0-3	NT by West	0-13 (or 15 = unknown)
4-7	NT by North	0-13 (or 15 = unknown)
8-11	NT by East	0-13 (or 15 = unknown)
12-15	NT by South	0-13 (or 15 = unknown)
16-79	… likewise in order for

A record starting with 16 null bits is impossible (it would mean each hand makes zero tricks in notrump) so this fact can be used to terminate a list of records, thus allowing end detection.

Top Main

ZRD Format

ZRD is a stand-alone version of ZDD, in that each random deal is stored with its double-dummy results. This simplifies the reproduction of each deal at the expense of using 2.3 times the storage space.

Each record is 23 bytes (184 bits). The first 13 bytes (104 bits) follow the ZBD structure, and the last 10 bytes (80 bits) follow the ZDD structure. The bitmap of each record is shown below.

Bit Value Coding
0-1 A 0 = West; 1 = North; 2 = East; 3 = South
2-3 K 0 = West; 1 = North; 2 = East; 3 = South
4-103 … likewise in order for Q-2 A-2 A-2 A-2
104-107 NT by West 0-13 (or 15 = unknown)
108-111 NT by North 0-13 (or 15 = unknown)
112-115 NT by East 0-13 (or 15 = unknown)
116-119 NT by South 0-13 (or 15 = unknown)
120-183 … likewise in order for

Bit	Value	Coding
0-1	A	0 = West; 1 = North; 2 = East; 3 = South
2-3	K	0 = West; 1 = North; 2 = East; 3 = South
4-103	… likewise in order for Q-2 A-2 A-2 A-2
104-107	NT by West	0-13 (or 15 = unknown)
108-111	NT by North	0-13 (or 15 = unknown)
112-115	NT by East	0-13 (or 15 = unknown)
116-119	NT by South	0-13 (or 15 = unknown)
120-183	… likewise in order for

A record starting with 32 null bits is impossible (it would mean the first 16 cards go to West) so this fact can be used to terminate any list of records, thus allowing end detection.

Top Main

ZRJ Format

ZRJ is similar to ZRD but stores only the double-dummy results of one hand (in all five strains). Besides being extremely useful (typically my only concern is what one hand can make) the record size is ideal for computer architecture and data alignment.

Each record is 16 bytes (128 bits). The first 13 bytes (104 bits) follow the ZBD structure, and the last 3 bytes (24 bits) indicate the target hand and its makes in each strain (if known). The bitmap of each record is shown below.

Bit Value Coding
0-1 A 0 = West; 1 = North; 2 = East; 3 = South
2-3 K 0 = West; 1 = North; 2 = East; 3 = South
4-103 … likewise in order for Q-2 A-2 A-2 A-2
104-105 Hand 0 = West; 1 = North; 2 = East; 3 = South
106-107 (unused) 0
108-111 NT make 0-13 (or 15 = unknown)
112-127 … likewise in order for

Bit	Value	Coding
0-1	A	0 = West; 1 = North; 2 = East; 3 = South
2-3	K	0 = West; 1 = North; 2 = East; 3 = South
4-103	… likewise in order for Q-2 A-2 A-2 A-2
104-105	Hand	0 = West; 1 = North; 2 = East; 3 = South
106-107	(unused)	0
108-111	NT make	0-13 (or 15 = unknown)
112-127	… likewise in order for

A record starting with 32 null bits is impossible (it would mean the first 16 cards go to West) so this fact can be used to terminate any list of records, thus allowing end detection.

Top Main

BIN Format

This is not a specific format (like ZBS ZBD ZDD ZRD ZRJ) but simply an indication that the file’s contents are binary coded and unreadable. Accompanying each BIN file is a TXT file explaining the contents and structure used. Current BIN files include the following:

GHP.BIN Generic hand patterns
SHP.BIN Specific hand patterns
GSP.BIN Generic side patterns
SSP.BIN Specific side patterns
GSX.BIN Generic sideprints
SSX.BIN Specific sideprints
GDX.BIN Generic dealprints
GHC.BIN Generic high cards
SHC.BIN Specific high cards
ESH.BIN Every suit holding

Top Main

GHP.BIN	Generic hand patterns
SHP.BIN	Specific hand patterns
GSP.BIN	Generic side patterns
SSP.BIN	Specific side patterns
GSX.BIN	Generic sideprints
SSX.BIN	Specific sideprints
GDX.BIN	Generic dealprints
GHC.BIN	Generic high cards
SHC.BIN	Specific high cards
ESH.BIN	Every suit holding