# NumberLink Environment for Gymnasium
[](https://pypi.python.org/pypi/numberlink)
[](https://github.com/misaghsoltani/NumberLink/blob/main/LICENSE)
[](https://pypi.python.org/pypi/numberlink)
[](https://pixi.sh)
[](https://github.com/astral-sh/ruff)
[](https://microsoft.github.io/pyright/)
[](https://github.com/misaghsoltani/NumberLink/actions/workflows/publish_to_pypi.yml)
[](https://github.com/misaghsoltani/NumberLink/actions/workflows/docs.yml)
[](https://colab.research.google.com/github/misaghsoltani/NumberLink/blob/main/notebooks/run_human.ipynb)
<br/>
<p align="center">
<img alt="NumberLink Logo" src="https://raw.githubusercontent.com/misaghsoltani/NumberLink/master/docs/_static/numberlink-logo.svg" />
</p>
<br/>
A Gymnasium environment for the NumberLink puzzle game.
## Gameplay Rules
NumberLink connects matching endpoints with non overlapping paths on a grid.
NumberLink boards follow these invariants:
- Every pair of endpoints must be connected by a single path. Endpoints are enumerated in `numberlink.level_setup.LevelTemplate` and copied into the environment state.
- Paths cannot branch or reuse grid cells. The environment enforces this through the action mask returned by `numberlink.env.NumberLinkRGBEnv.reset` and `numberlink.env.NumberLinkRGBEnv.step`.
- Unless the chosen variant disables the requirement, every cell must belong to a path. Toggle this rule with `numberlink.config.VariantConfig.must_fill`.
- Bridge cells yield independent vertical and horizontal lanes governed by `numberlink.config.VariantConfig.bridges_enabled`.
- Diagonal moves are allowed only when `numberlink.config.VariantConfig.allow_diagonal` is set. Cell switching is controlled by `numberlink.config.VariantConfig.cell_switching_mode`.
## Quick links
- Home page & documentation: [NumberLink](https://misaghsoltani.github.io/NumberLink/)
- Quick start: [Quick Start](#quick-start)
- Google Colab: [Open in Colab](https://colab.research.google.com/github/misaghsoltani/NumberLink/blob/main/notebooks/run_human.ipynb)
- Installation guide: [Installation - documentation](https://misaghsoltani.github.io/NumberLink/installation.html)
- CLI reference: [CLI - documentation](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.cli.html)
- Python API: [API reference - documentation](https://misaghsoltani.github.io/NumberLink/apidocs/index.html)
- Citing this project: [Cite this project](#cite-this-work)
- Contact: [Contact](#contact)
### Demo
|  |  |  |  |
| :------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: |
## Quick start
The [NumberLink documentation](https://misaghsoltani.github.io/NumberLink/) covers every workflow in detail. The
highlights below show the recommended [Gymnasium](https://gymnasium.farama.org/) >= 1.0 usage patterns. You can also try it out in the [Google Colab example](https://colab.research.google.com/github/misaghsoltani/NumberLink/blob/main/notebooks/run_human.ipynb).
### Install from PyPI
#### Using pip
```bash
pip install numberlink
```
#### Install with [uv](https://docs.astral.sh/uv/)
```bash
uv pip install numberlink
```
#### Enable notebook integration
Install the optional notebook dependencies to enable inline controls in Jupyter and Google Colab:
```bash
pip install "numberlink[notebook]"
```
With `uv`:
```bash
uv pip install "numberlink[notebook]"
```
See the [installation guide](https://misaghsoltani.github.io/NumberLink/installation.html) for Pixi, Conda, and source build instructions.
### Create a single environment
```python
import gymnasium as gym
import numpy as np
import numberlink # Auto-registers the NumberLink environments
env = gym.make("NumberLinkRGB-v0", render_mode="rgb_array")
observation, info = env.reset(seed=42)
action_mask = info["action_mask"]
terminated = False
truncated = False
while not (terminated or truncated):
action = env.action_space.sample(mask=action_mask)
observation, reward, terminated, truncated, info = env.step(action)
action_mask = info["action_mask"]
action_mask = info["action_mask"].astype(np.int8)
env.close()
```
Configuration objects such as
[GeneratorConfig](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.config.html#numberlink.config.GeneratorConfig),
[VariantConfig](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.config.html#numberlink.config.VariantConfig),
and [RenderConfig](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.config.html#numberlink.config.RenderConfig)
customize generation, gameplay rules, and rendering. Examples live in the
[usage guide](https://misaghsoltani.github.io/NumberLink/usage.html) and the
[level setup module](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.level_setup.html).
### Run vectorized environments
```python
import gymnasium as gym
from numberlink import GeneratorConfig # Auto-registers the NumberLink environments
import numpy as np
vec_env = gym.make_vec(
"NumberLinkRGB-v0",
num_envs=4,
render_mode="rgb_array",
generator=GeneratorConfig(width=6, height=6, colors=4),
)
observations, infos = vec_env.reset(seed=0)
actions = [vec_env.single_action_space.sample(mask=mask) for mask in infos["action_mask"]]
actions = [vec_env.single_action_space.sample(mask=mask.astype(np.int8)) for mask in infos["action_mask"]]
observations, rewards, terminated, truncated, infos = vec_env.step(actions)
vec_env.close()
```
Gymnasium auto resets terminated slots when the vector environment is configured with the default autoreset mode. See
the [vector API section of the docs](https://misaghsoltani.github.io/NumberLink/usage.html#vector-environment) for
batched workflows.
### Human render mode
```python
import gymnasium as gym
import numberlink
from numberlink.viewer import NumberLinkViewer
numberlink.register_numberlink_v0()
env = gym.make("NumberLinkRGB-v0", render_mode="human")
viewer = NumberLinkViewer(env)
viewer.loop()
```
The pygame viewer mirrors the CLI command shown in
[examples/run_human.py](https://github.com/misaghsoltani/NumberLink/blob/main/examples/run_human.py) and is documented
at [viewer API](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.viewer.html).
### Notebook viewer
The package ships an inline viewer that mirrors the pygame controls when the optional notebook extras are installed.
```python
env = gym.make(
"NumberLinkRGB-v0",
render_mode="human",
generator=GeneratorConfig( mode="hamiltonian", colors=7, width=8, height=8, must_fill=True, min_path_length=3),
variant=VariantConfig(allow_diagonal=False, cell_switching_mode=False, bridges_enabled=False),
render_config=RenderConfig(gridline_color=(60, 60, 60),gridline_thickness=1,show_endpoint_numbers=True,render_height=400,render_width=400),
)
env.reset()
viewer = NumberLinkViewer(env, cell_size=64)
viewer.loop()
```
`NumberLinkViewer.loop()` auto-detects notebook runtimes. When the optional dependencies are available it displays the
inline widgets, otherwise it shows an installation hint so the classic pygame window is not opened in headless
contexts.
## Auto-registration
Recommended usage is to install the package (for example via PyPI), and Gymnasium then discovers the environments via
the package's entry-points.
See the [documentation](https://misaghsoltani.github.io/NumberLink/) for more details.
## License
MIT License - see [LICENSE](https://github.com/misaghsoltani/NumberLink/blob/main/LICENSE).
## Cite this work
If you use NumberLink in your research, please cite:
<!-- CITATION-BIBTEX:START -->
```bibtex
@misc{numberlinkenv2025soltani,
author = {Soltani, Misagh},
title = {NumberLink Puzzle},
url = {https://misaghsoltani.github.io/NumberLink},
year = {2025}
}
```
<!-- CITATION-BIBTEX:END -->
## Contact
If you have any questions or issues, please contact Misagh Soltani ([misaghsoltani@gmail.com](mailto:misaghsoltani@gmail.com))
Raw data
{
"_id": null,
"home_page": null,
"name": "numberlink",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "AI, Game, Gymnasium, NumberLink, OpenAI Gym, Puzzle, deep reinforcement learning, gym, heuristic search, pathfinding, planning, reinforcement learning, search",
"author": null,
"author_email": "Misagh Soltani <misaghsoltani@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2a/ef/3556cd8d95a35cfbbbcf30f6180596507ce55adb8a9948b546455e2de1bf/numberlink-0.1.3.tar.gz",
"platform": null,
"description": "# NumberLink Environment for Gymnasium\n\n[](https://pypi.python.org/pypi/numberlink)\n[](https://github.com/misaghsoltani/NumberLink/blob/main/LICENSE)\n[](https://pypi.python.org/pypi/numberlink)\n[](https://pixi.sh)\n[](https://github.com/astral-sh/ruff)\n[](https://microsoft.github.io/pyright/)\n\n[](https://github.com/misaghsoltani/NumberLink/actions/workflows/publish_to_pypi.yml)\n[](https://github.com/misaghsoltani/NumberLink/actions/workflows/docs.yml)\n[](https://colab.research.google.com/github/misaghsoltani/NumberLink/blob/main/notebooks/run_human.ipynb)\n\n<br/>\n\n<p align=\"center\">\n <img alt=\"NumberLink Logo\" src=\"https://raw.githubusercontent.com/misaghsoltani/NumberLink/master/docs/_static/numberlink-logo.svg\" />\n</p>\n\n<br/>\n\nA Gymnasium environment for the NumberLink puzzle game.\n\n## Gameplay Rules\n\nNumberLink connects matching endpoints with non overlapping paths on a grid.\n\nNumberLink boards follow these invariants:\n\n- Every pair of endpoints must be connected by a single path. Endpoints are enumerated in `numberlink.level_setup.LevelTemplate` and copied into the environment state.\n- Paths cannot branch or reuse grid cells. The environment enforces this through the action mask returned by `numberlink.env.NumberLinkRGBEnv.reset` and `numberlink.env.NumberLinkRGBEnv.step`.\n- Unless the chosen variant disables the requirement, every cell must belong to a path. Toggle this rule with `numberlink.config.VariantConfig.must_fill`.\n- Bridge cells yield independent vertical and horizontal lanes governed by `numberlink.config.VariantConfig.bridges_enabled`.\n- Diagonal moves are allowed only when `numberlink.config.VariantConfig.allow_diagonal` is set. Cell switching is controlled by `numberlink.config.VariantConfig.cell_switching_mode`.\n\n## Quick links\n\n- Home page & documentation: [NumberLink](https://misaghsoltani.github.io/NumberLink/)\n- Quick start: [Quick Start](#quick-start)\n- Google Colab: [Open in Colab](https://colab.research.google.com/github/misaghsoltani/NumberLink/blob/main/notebooks/run_human.ipynb)\n- Installation guide: [Installation - documentation](https://misaghsoltani.github.io/NumberLink/installation.html)\n- CLI reference: [CLI - documentation](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.cli.html)\n- Python API: [API reference - documentation](https://misaghsoltani.github.io/NumberLink/apidocs/index.html)\n- Citing this project: [Cite this project](#cite-this-work)\n- Contact: [Contact](#contact)\n\n### Demo\n\n|  |  |  |  |\n| :------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: |\n\n## Quick start\n\nThe [NumberLink documentation](https://misaghsoltani.github.io/NumberLink/) covers every workflow in detail. The\nhighlights below show the recommended [Gymnasium](https://gymnasium.farama.org/) >= 1.0 usage patterns. You can also try it out in the [Google Colab example](https://colab.research.google.com/github/misaghsoltani/NumberLink/blob/main/notebooks/run_human.ipynb).\n\n### Install from PyPI\n\n#### Using pip\n\n```bash\npip install numberlink\n```\n\n#### Install with [uv](https://docs.astral.sh/uv/)\n\n```bash\nuv pip install numberlink\n```\n\n#### Enable notebook integration\n\nInstall the optional notebook dependencies to enable inline controls in Jupyter and Google Colab:\n\n```bash\npip install \"numberlink[notebook]\"\n```\n\nWith `uv`:\n\n```bash\nuv pip install \"numberlink[notebook]\"\n```\n\nSee the [installation guide](https://misaghsoltani.github.io/NumberLink/installation.html) for Pixi, Conda, and source build instructions.\n\n### Create a single environment\n\n```python\nimport gymnasium as gym\nimport numpy as np\n\nimport numberlink # Auto-registers the NumberLink environments\n\n\nenv = gym.make(\"NumberLinkRGB-v0\", render_mode=\"rgb_array\")\n\nobservation, info = env.reset(seed=42)\naction_mask = info[\"action_mask\"]\n\nterminated = False\ntruncated = False\n\nwhile not (terminated or truncated):\n action = env.action_space.sample(mask=action_mask)\n observation, reward, terminated, truncated, info = env.step(action)\n action_mask = info[\"action_mask\"]\n action_mask = info[\"action_mask\"].astype(np.int8)\n\nenv.close()\n```\n\nConfiguration objects such as\n[GeneratorConfig](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.config.html#numberlink.config.GeneratorConfig),\n[VariantConfig](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.config.html#numberlink.config.VariantConfig),\nand [RenderConfig](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.config.html#numberlink.config.RenderConfig)\ncustomize generation, gameplay rules, and rendering. Examples live in the\n[usage guide](https://misaghsoltani.github.io/NumberLink/usage.html) and the\n[level setup module](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.level_setup.html).\n\n### Run vectorized environments\n\n```python\nimport gymnasium as gym\nfrom numberlink import GeneratorConfig # Auto-registers the NumberLink environments\nimport numpy as np\n\nvec_env = gym.make_vec(\n \"NumberLinkRGB-v0\",\n num_envs=4,\n render_mode=\"rgb_array\",\n generator=GeneratorConfig(width=6, height=6, colors=4),\n)\n\nobservations, infos = vec_env.reset(seed=0)\nactions = [vec_env.single_action_space.sample(mask=mask) for mask in infos[\"action_mask\"]]\nactions = [vec_env.single_action_space.sample(mask=mask.astype(np.int8)) for mask in infos[\"action_mask\"]]\nobservations, rewards, terminated, truncated, infos = vec_env.step(actions)\nvec_env.close()\n```\n\nGymnasium auto resets terminated slots when the vector environment is configured with the default autoreset mode. See\nthe [vector API section of the docs](https://misaghsoltani.github.io/NumberLink/usage.html#vector-environment) for\nbatched workflows.\n\n### Human render mode\n\n```python\nimport gymnasium as gym\nimport numberlink\nfrom numberlink.viewer import NumberLinkViewer\n\nnumberlink.register_numberlink_v0()\nenv = gym.make(\"NumberLinkRGB-v0\", render_mode=\"human\")\nviewer = NumberLinkViewer(env)\nviewer.loop()\n```\n\nThe pygame viewer mirrors the CLI command shown in\n[examples/run_human.py](https://github.com/misaghsoltani/NumberLink/blob/main/examples/run_human.py) and is documented\nat [viewer API](https://misaghsoltani.github.io/NumberLink/apidocs/numberlink/numberlink.viewer.html).\n\n### Notebook viewer\n\nThe package ships an inline viewer that mirrors the pygame controls when the optional notebook extras are installed.\n\n```python\nenv = gym.make(\n \"NumberLinkRGB-v0\",\n render_mode=\"human\",\n generator=GeneratorConfig( mode=\"hamiltonian\", colors=7, width=8, height=8, must_fill=True, min_path_length=3),\n variant=VariantConfig(allow_diagonal=False, cell_switching_mode=False, bridges_enabled=False),\n render_config=RenderConfig(gridline_color=(60, 60, 60),gridline_thickness=1,show_endpoint_numbers=True,render_height=400,render_width=400),\n)\nenv.reset()\n\nviewer = NumberLinkViewer(env, cell_size=64)\nviewer.loop()\n```\n\n`NumberLinkViewer.loop()` auto-detects notebook runtimes. When the optional dependencies are available it displays the\ninline widgets, otherwise it shows an installation hint so the classic pygame window is not opened in headless\ncontexts.\n\n## Auto-registration\n\nRecommended usage is to install the package (for example via PyPI), and Gymnasium then discovers the environments via\nthe package's entry-points.\n\nSee the [documentation](https://misaghsoltani.github.io/NumberLink/) for more details.\n\n## License\n\nMIT License - see [LICENSE](https://github.com/misaghsoltani/NumberLink/blob/main/LICENSE).\n\n## Cite this work\n\nIf you use NumberLink in your research, please cite:\n\n<!-- CITATION-BIBTEX:START -->\n```bibtex\n@misc{numberlinkenv2025soltani,\n author = {Soltani, Misagh},\n title = {NumberLink Puzzle},\n url = {https://misaghsoltani.github.io/NumberLink},\n year = {2025}\n}\n```\n<!-- CITATION-BIBTEX:END -->\n\n## Contact\n\nIf you have any questions or issues, please contact Misagh Soltani ([misaghsoltani@gmail.com](mailto:misaghsoltani@gmail.com))\n",
"bugtrack_url": null,
"license": null,
"summary": "NumberLink puzzle environment for Gymnasium",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://misaghsoltani.github.io/NumberLink/",
"GitHub": "https://github.com/misaghsoltani/NumberLink/"
},
"split_keywords": [
"ai",
" game",
" gymnasium",
" numberlink",
" openai gym",
" puzzle",
" deep reinforcement learning",
" gym",
" heuristic search",
" pathfinding",
" planning",
" reinforcement learning",
" search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f859b733c311d5079846af2cc6e46526bc0cac89c7993b121574124c346b72e6",
"md5": "a2fc5995b6f1fd03e5c4d5b543f5db66",
"sha256": "8dc909849ca9c344b42962bf2bed9b37a76281ee268b681b3489151ca2da4bae"
},
"downloads": -1,
"filename": "numberlink-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2fc5995b6f1fd03e5c4d5b543f5db66",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 119213,
"upload_time": "2025-10-22T19:30:00",
"upload_time_iso_8601": "2025-10-22T19:30:00.101491Z",
"url": "https://files.pythonhosted.org/packages/f8/59/b733c311d5079846af2cc6e46526bc0cac89c7993b121574124c346b72e6/numberlink-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2aef3556cd8d95a35cfbbbcf30f6180596507ce55adb8a9948b546455e2de1bf",
"md5": "6f24bda75abe1f15fe50ff5e5abada48",
"sha256": "8965e8e9a2f24651111340992c5b4b4d877d5ae78f6104496ffc01e75f7541a5"
},
"downloads": -1,
"filename": "numberlink-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "6f24bda75abe1f15fe50ff5e5abada48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 103419,
"upload_time": "2025-10-22T19:30:01",
"upload_time_iso_8601": "2025-10-22T19:30:01.567120Z",
"url": "https://files.pythonhosted.org/packages/2a/ef/3556cd8d95a35cfbbbcf30f6180596507ce55adb8a9948b546455e2de1bf/numberlink-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 19:30:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "misaghsoltani",
"github_project": "NumberLink",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"<",
"3"
],
[
">=",
"2.0"
]
]
},
{
"name": "pygame",
"specs": [
[
"<",
"3"
],
[
">=",
"2.0"
]
]
},
{
"name": "gymnasium",
"specs": [
[
"<",
"2"
],
[
">=",
"1.0"
]
]
}
],
"lcname": "numberlink"
}
JSON
