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.
ZBSZBDZDDZRDZRJBIN

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.

BitValueCoding
0Flag0 = end of group; 1 = next record same group
1-31Locator0 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.

BitValueCoding
0-1S A0 = West; 1 = North; 2 = East; 3 = South
2-3S K0 = West; 1 = North; 2 = East; 3 = South
4-103Likewise in order for S Q-2 H A-2 D A-2 C 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.

BitValueCoding
0-3NT by West0-13 (or 15 = unknown)
4-7NT by North0-13 (or 15 = unknown)
8-11NT by East0-13 (or 15 = unknown)
12-15NT by South0-13 (or 15 = unknown)
16-79Likewise in order for S H D C

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.

BitValueCoding
0-1S A0 = West; 1 = North; 2 = East; 3 = South
2-3S K0 = West; 1 = North; 2 = East; 3 = South
4-103 Likewise in order for S Q-2 H A-2 D A-2 C A-2
104-107NT by West0-13 (or 15 = unknown)
108-111NT by North0-13 (or 15 = unknown)
112-115NT by East0-13 (or 15 = unknown)
116-119NT by South0-13 (or 15 = unknown)
120-183 Likewise in order for S H D C

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.

BitValueCoding
0-1S A0 = West; 1 = North; 2 = East; 3 = South
2-3S K0 = West; 1 = North; 2 = East; 3 = South
4-103 Likewise in order for S Q-2 H A-2 D A-2 C A-2
104-105Hand0 = West; 1 = North; 2 = East; 3 = South
106-107(unused)0
108-111NT make0-13 (or 15 = unknown)
112-127 Likewise in order for S H D C

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

BIN 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:

FileExplanation
GHP.BINGeneric hand patterns
SHP.BINSpecific hand patterns
GSP.BINGeneric side patterns
SSP.BINSpecific side patterns
GSX.BINGeneric sideprints
SSX.BINSpecific sideprints
GDX.BINGeneric dealprints
ESH.BINEvery Suit Holding
GHC.BINGeneric high cards
SHC.BINSpecific high cards
SCO.BINBridge Result Scores
Top     Main

© 2016 Richard Pavlicek