shanten-algorithm-collection

Shanten Number Calculation Algorithm Collection

This project is a collection for implementing and comparing multiple algorithms to calculate the shanten number (向聴数). It provides a common interface and test macros to make it easy to implement and verify each algorithm.

Important

This project targets only the general form of hands consisting of n melds and 1 pair.
Seven Pairs (Chiitoitsu, 七対子) and Thirteen Orphans (Kokushi Musou, 国士無双) hand types are excluded.

For a detailed definition of the shanten number, please refer to 結局のところ，麻雀における向聴数とは数学的かつ構成的にどう定義されるのか？ #数学 - Qiita.

Components

common

A common library for implementing shanten number calculation algorithms. Provides traits, types, and test macros required for algorithm implementation.

handgen

A utility for generating random mahjong hands for benchmarking. It outputs 10,000 cases each for four types of 14-tile hands (normal, half flush, full flush, thirteen orphans) as text files, where each hand is represented as an array of 14 tile indices (0–33).

resources

This directory stores random hand data (text files) generated by handgen.

dummy

An example implementation of a dummy shanten number calculation algorithm. Useful as a reference for implementation and test macro usage.

algorithms

Contains various implementations of shanten number calculation algorithms.

Usage

1. To add a new algorithm, first create a directory as a subcrate using the following command:

   cargo new --lib algorithms/your_algorithm

   Replace your_algorithm with the desired subcrate name.

2. Next, implement the common::ShantenCalculator trait in your subcrate.

3. For testing, you can use the common::shanten_tests! macro to automatically generate test cases.

4. For benchmarking, you can use the common::shanten_benches! macro to automatically generate benchmarks.

5. To run the tests for your algorithm, execute the following command:

   cargo +nightly test --package your_algorithm

   Replace your_algorithm with the name of your subcrate.

6. To run the benchmarks for your algorithm, execute the following command:

   cargo +nightly bench --package your_algorithm

   Replace your_algorithm with the name of your subcrate.

Example Implementation

#![feature(test)]

extern crate test;

use common::{ShantenCalculator, TileCounts};
use common::{shanten_benches, shanten_tests};

struct YourAlgorithm {}

impl ShantenCalculator for YourAlgorithm {
    fn new() -> Self { YourAlgorithm {} }
    fn calculate_shanten(&self, hand: &TileCounts) -> i8 {
        // Algorithm implementation
        0
    }
}

shanten_tests!(YourAlgorithm);
shanten_benches!(YourAlgorithm);

License

Copyright (c) Apricot S. All rights reserved.

Licensed under the MIT license.