Mortal

https://mortal.ekyu.moe/
Admin
Mortal is an open-source Japanese riichi mahjong AI powered by deep reinforcement learning,...
Tokens:7,026
Snippets:56
Trust Score:8
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and build documentation

Source: https://mortal.ekyu.moe/user/build.html

Installs mdbook and related plugins, then builds the documentation.

```bash
$ cargo install mdbook mdbook-admonish mdbook-pagetoc
$ mdbook build

```

--------------------------------

### Verify libriichi installation

Source: https://mortal.ekyu.moe/user/build.html

Starts a Python interpreter and imports libriichi to verify the installation. Shows the expected output when the library is correctly installed.

```python
$ python
Python 3.9.7 | packaged by conda-forge | (default, Sep 29 2021, 19:23:11)
[GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import libriichi
>>> help(libriichi)

```

--------------------------------

### Create and activate conda environment

Source: https://mortal.ekyu.moe/user/build.html

Creates a conda environment from environment.yml and activates it. Requires miniconda and Rust to be installed.

```bash
$ conda env create -f environment.yml
$ conda activate mortal

```

--------------------------------

### Mjai events for the next scene (9p discard, 1m pon pass)

Source: https://mortal.ekyu.moe/user/docker.html

Sequence of mjai events the player perceived since the previous scene. Paste these into the running process's input or append to `log.json` and re-run the command to get Mortal's reactions.

```json
{"type":"dahai","actor":2,"pai":"9p","tsumogiri":true}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"2p","tsumogiri":true}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"8s","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"1m","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"3p"}
```

--------------------------------

### Mortal mjai reaction JSON for discarding 9p

Source: https://mortal.ekyu.moe/user/docker.html

Example output from Mortal's mjai reaction stream. The `meta` field is not defined in mjai and is optional; it records network raw outputs and evaluation time. Here Mortal discards 9p.

```json
{
  "type": "dahai",
  "actor": 2,
  "pai": "9p",
  "tsumogiri": true,
  "meta": {
    "q_values": [
      -1.1929103,
      -1.5628747,
      -1.6204606,
      -1.607082,
      -1.3267958,
      -0.2436666,
      -1.5208447,
      -1.5280346,
      -1.5830542,
      -1.6640469,
      -1.1801766,
      -1.8054415
    ],
    "mask_bits": 17241923593,
    "is_greedy": true,
    "batch_size": 1,
    "shanten": 1,
    "eval_time_ns": 30352000
  }
}
```

--------------------------------

### mjai game log JSON Lines for mortal

Source: https://mortal.ekyu.moe/user/docker.html

A complete mjai game log in JSON Lines format, starting with start_game and start_kyoku events and ending mid-hand after a tsumo. It includes tsumo, dahai, pon, reach, and reach_accepted events with actor, pai, and tsumogiri fields. Save this content to a file named log.json before running the mortal Docker command.

```json
{"type":"start_game"}
{"type":"start_kyoku","bakaze":"E","dora_marker":"3s","kyoku":3,"honba":0,"kyotaku":0,"oya":2,"scores":[22000,23700,26000,28300],"tehais":[["?","?","?","?","?","?","?","?","?","?","?","?","?"],["?","?","?","?","?","?","?","?","?","?","?","?","?"],["1m","1m","4m","5m","1p","5p","8p","1s","4s","4s","6s","8s","N"],["?","?","?","?","?","?","?","?","?","?","?","?","?"]]}
{"type":"tsumo","actor":2,"pai":"6p"}
{"type":"dahai","actor":2,"pai":"1s","tsumogiri":false}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"1s","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"9s","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"9p","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"3s"}
{"type":"dahai","actor":2,"pai":"N","tsumogiri":false}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"9m","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"1m","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"1s","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"7s"}
{"type":"dahai","actor":2,"pai":"1p","tsumogiri":false}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"W","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"1p","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"W","tsumogiri":false}
{"type":"pon","actor":0,"target":1,"pai":"W","consumed":["W","W"]}
{"type":"dahai","actor":0,"pai":"2p","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"9s","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"P"}
{"type":"dahai","actor":2,"pai":"8p","tsumogiri":false}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"C","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"9p","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"1s","tsumogiri":true}
{"type":"tsumo","actor":2,"pai":"7m"}
{"type":"dahai","actor":2,"pai":"7m","tsumogiri":true}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"7p","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"C","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"2s","tsumogiri":true}
{"type":"tsumo","actor":2,"pai":"6s"}
{"type":"dahai","actor":2,"pai":"6s","tsumogiri":true}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"E","tsumogiri":true}
{"type":"pon","actor":1,"target":3,"pai":"E","consumed":["E","E"]}
{"type":"dahai","actor":1,"pai":"2m","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"7p"}
{"type":"dahai","actor":2,"pai":"P","tsumogiri":false}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"8s","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"E","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"4p","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"8p"}
{"type":"dahai","actor":2,"pai":"8p","tsumogiri":true}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"9s","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"S","tsumogiri":true}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"6s","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"9m"}
{"type":"dahai","actor":2,"pai":"9m","tsumogiri":true}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"2p","tsumogiri":false}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"2s","tsumogiri":true}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"8p","tsumogiri":true}
{"type":"tsumo","actor":2,"pai":"F"}
{"type":"dahai","actor":2,"pai":"F","tsumogiri":true}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"dahai","actor":3,"pai":"4p","tsumogiri":true}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"4m","tsumogiri":true}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"S","tsumogiri":true}
{"type":"tsumo","actor":2,"pai":"5mr"}
{"type":"dahai","actor":2,"pai":"5m","tsumogiri":false}
{"type":"tsumo","actor":3,"pai":"?"}
{"type":"reach","actor":3}
{"type":"dahai","actor":3,"pai":"N","tsumogiri":false}
{"type":"reach_accepted","actor":3}
{"type":"tsumo","actor":0,"pai":"?"}
{"type":"dahai","actor":0,"pai":"N","tsumogiri":false}
{"type":"tsumo","actor":1,"pai":"?"}
{"type":"dahai","actor":1,"pai":"F","tsumogiri":false}
{"type":"tsumo","actor":2,"pai":"9p"}
```

--------------------------------

### Build libriichi binaries and exe-wrapper

Source: https://mortal.ekyu.moe/user/build.html

Builds the libriichi binaries and the exe-wrapper in release mode.

```bash
$ cargo build -p libriichi --bins --no-default-features --release
$ cargo build -p exe-wrapper --release

```

--------------------------------

### Build Mortal Docker image

Source: https://mortal.ekyu.moe/user/docker.html

Clones the Mortal repository and builds the Docker image with BuildKit. Requires sudo and Docker with BuildKit support. The image is intended for inference only, not training.

```bash
$ git clone https://github.com/Equim-chan/Mortal.git
$ cd Mortal
$ sudo env DOCKER_BUILDKIT=1 docker build -t mortal:latest .
```

--------------------------------

### Run libriichi benchmarks

Source: https://mortal.ekyu.moe/user/build.html

Runs benchmarks for the libriichi crate.

```bash
$ cargo test -p libriichi --no-default-features --bench bench

```

--------------------------------

### Run workspace tests

Source: https://mortal.ekyu.moe/user/build.html

Runs all tests in the workspace with the flate2/zlib feature enabled.

```bash
$ cargo test --workspace --no-default-features --features flate2/zlib -- --nocapture

```

--------------------------------

### Clone the Mortal repository

Source: https://mortal.ekyu.moe/user/build.html

Clones the Mortal repository from GitHub and changes into the project directory.

```bash
$ git clone https://github.com/Equim-chan/Mortal.git
$ cd Mortal

```

--------------------------------

### Run mortal Docker container with mjai log

Source: https://mortal.ekyu.moe/user/docker.html

Runs the mortal Docker container in interactive mode, mounting the model directory to /mnt and feeding the mjai log from log.json via stdin. The -i flag keeps stdin open, --rm removes the container after exit, and the -v flag binds the host model directory to /mnt.

```bash
$ sudo docker run -i --rm -v /path/to/model/dir:/mnt mortal 2 < log.json
```

--------------------------------

### Copy libriichi library for Windows (MSYS2)

Source: https://mortal.ekyu.moe/user/build.html

Copies the compiled DLL to the mortal package directory for Windows (MSYS2) systems.

```bash
$ cp target/release/riichi.dll mortal/libriichi.pyd

```

--------------------------------

### Build libriichi Rust library

Source: https://mortal.ekyu.moe/user/build.html

Compiles the libriichi library in release mode. This is required before copying the library to the Python package.

```bash
$ cargo build -p libriichi --lib --release

```

--------------------------------

### Copy libriichi library for Linux

Source: https://mortal.ekyu.moe/user/build.html

Copies the compiled shared library to the mortal package directory for Linux systems.

```bash
$ cp target/release/libriichi.so mortal/libriichi.so

```

--------------------------------

### Mortal mjai reaction JSON for passing 1m pon

Source: https://mortal.ekyu.moe/user/docker.html

Mortal's reaction to the 1m pon: a `none` action meaning it passes the pon. The `meta` field is optional and records network outputs and evaluation time.

```json
{
  "type": "none",
  "meta": {
    "q_values": [
      -1.2190987,
      -0.084070235
    ],
    "mask_bits": 37383395344384,
    "is_greedy": true,
    "batch_size": 1,
    "shanten": 1,
    "eval_time_ns": 29667100
  }
}
```

--------------------------------

### Mortal mjai reaction JSON for discarding 1m

Source: https://mortal.ekyu.moe/user/docker.html

Mortal's reaction to the next scene: a `dahai` event discarding 1m. The `meta` field is optional and records network outputs and evaluation time.

```json
{
  "type": "dahai",
  "actor": 2,
  "pai": "1m",
  "tsumogiri": false,
  "meta": {
    "q_values": [
      -0.22652823,
      -1.7668037,
      -1.0071788,
      -1.7482929,
      -1.7783809,
      -1.5943735,
      -1.5575972,
      -1.5641792,
      -1.6780779,
      -1.7836256,
      -1.5739789,
      -1.915102
    ],
    "mask_bits": 17241794569,
    "is_greedy": true,
    "batch_size": 1,
    "eval_time_ns": 29686500
  }
}
```
Tokens:
Raw