Noqx

Extended logic puzzle solver of Noq.

Current Maintainers

• @T0nyX1ang: backend, frontend, new solver implementations, bug fixes

• @zhuyaoyu: (huge) solver optimizations, new solver implementations, bug fixes

New features

New features from Noq

• Remove redundant codes and formatting codes.

• New solver backend with new UI design (See issue #2)

• Change the backend from Django to Starlette with Uvicorn (See issue #31, #50).

• Change the frontend from Noq native to penpa-edit. (See issue #36).

New usages from Penpa-edit

• Select puzzle type.

• Show rules in puzz.link if possible.

• Choose example puzzle.

• Show/Edit parameters of the solver if possible.

• Solve/Reset the puzzle.

Note: if the puzzle is imported from puzz.link, you will need to change the edit mode to Problem to reset the puzzle itself.

How to run locally

Use uv with a virtual environment (Recommended)

• Install uv first.

• Clone this project and switch to master branch.

    git clone https://github.com/T0nyX1ang/noqx.git

• Create a virtual environment (Optional):

    uv venv

• Install non-development packages with uv:

    uv sync --no-dev

• Run with uv:

    uv run noqx.py

Use PIP

• Install requirements (automatically generated by uv):

    pip install -r requirements.txt

• Clone this project and switch to master branch.

    git clone https://github.com/T0nyX1ang/noqx.git

• Run locally (based on your system):

    py -3 noqx.py
    python3 noqx.py

Additional Usage

    usage: noqx.py [-h] [-d] [-H HOST] [-p PORT] [-tl TIME_LIMIT]

    optional arguments:
      -h, --help            show this help message and exit
      -H HOST, --host HOST  the host to run the server on.
      -p PORT, --port PORT  the port to run the server on.
      -d, --debug           whether to enable debug mode with auto-reloading.
      -tl TIME_LIMIT, --time_limit TIME_LIMIT
                            time limit in seconds (default = 30).
      -pt PARALLEL_THREADS, --parallel_threads PARALLEL_THREADS
                            parallel threads (default = 1).

How to contribute

Preparations

• Install uv first.

• Clone this project and switch to dev branch.

    git clone https://github.com/T0nyX1ang/noqx.git
    git checkout dev

• Install all dependencies with uv:

    uv sync

• Install pre-commit and add commit hooks:

    uv pre-commit install

Write a new solver

• Create a python file in solver/ and write solver codes in that file. The functions in noqx package are free to use.

• (Optional) Append a __metadata__ variable in the end of the solver file. The keys of __metadata__ are:

  • name: the name of the solver.
  • category: the category of the solver, should be shade (Shading), loop (Loop / Path), region (Area Division), num (Number), var (Variety), draw (Drawing), unk (Unknown).
  • examples (Optional): a list of examples of the solver, each example can be created in two conflicting ways, data and url:
  • data: directly draw the board in noqx and get the data URL by using Share → Editing URL → Copy.
  • url: draw the board in puzz.link and use File → Export URL to get the board URL.
  • config (Optional): the configuration of the solver, which will be passed to the solver when it is created, and the keys of config are the same as parameters keys.
  • test (Optional): whether the example is a test case, the default value is True, and cannot be used together with url way.
  • parameters (Optional): the parameters of the solver, which will be passed to the solver when it is created.

• Free to PR now ^_^

Test solvers

• Run the tests (with default unittest features) with uv:

    uv run coverage run -m unittest

• Check the HTML version of coverage report with uv:

    uv run coverage html

License

• This project is dual-licensed under Apache 2.0 and GPL 3.0 (or any later version). You can choose between one of them if you use this project.