QSolve is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install qsolve

It will make the qsolve command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall qsolve uninstalls.

Adding `qsolve` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add qsolve

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

qsolve = "1.0.0"

The qsolve library will be automatically available globally. Read the qsolve library documentation.

Back to the crate overview.

Readme

QSolve

A command line tool and library for solving Queens puzzles

An animation of a Queens puzzle being solved"

This command line tool and library is designed to solve Queens puzzles, with a few key characteristics:

Human-understandable: Humans solve queens by iteratively eliminating and confirming squares. This library does the same process; it doesn't use and do any sort of search-algorithms to try and find the solution from afar.
Fast: Within the bounds of the above, it tries to be as fast as possible. This means, for example, it uses bitfields rather than HashSets for efficient operations on small sets.
Tested: While tracing code and error recovery means this library doesn't have 100% code coverage, it aspires to be as well-tested as possible. If cargo test passes, then we should be confident things work.
Documented: The qsolve binary should have clear documentation available with --help for every subcommand. The qsolve library should have clear documentation (including doctests) for all public functionality.

Installation

qsolve can be installed from crates.io by running

cargo install qsolve

Alternately, the binary can be downloaded directly from Github releases.

Command line example

Basic usage of the command line tool looks something like this:

qsolve solve games/linkedin-1-empty.txt --share

which yields the following screenshot (throughout this README, screenshots will be used since the command line tool relies heavily on ANSI color strings to output Queens boards):

A terminal showing the results of running "qsolve solve games/linkedin-1-empty.txt --share"

More compelling, though, is the animate subcommand, which doesn't just solve the puzzle, but walks you through the solution step by step.

https://github.com/user-attachments/assets/6b4d6798-63be-4000-b850-c8a45008dd1d

Library Example

Basic usage of the library looks something like this:

use std::path::PathBuf;
use qsolve::heuristic::all_heuristics;
use qsolve::file::QueensFile;
use qsolve::solveiter::solve_iter;
use qsolve::solvestate::{SolveState, SolveStrategy};

fn solve() -> Result<(), Box<dyn std::error::Error>> {
    // Parse a text file containing a Queens puzzle.
    let queens_file = QueensFile::try_from_text_file(&PathBuf::from("games/linkedin-1-empty.txt"))?;

    // Generate the initial solve state and print it.
    let solve_state = SolveState::from(&queens_file);
    println!("{}", solve_state);

    // Generate the list of heuristics to use to solve the puzzle.
    let heuristics = all_heuristics(solve_state.board);

    // Solve the puzzle and print out the solution.
    let solved = solve_iter(solve_state, SolveStrategy::Fast, &heuristics).last().unwrap().solve_state;
    println!("{}", solved);

    Ok(())
}

Development

qsolve is a side project, so development will happen in a pretty ad-hoc basis (and issues and PRs might go unanswered: caveat emptor). However, if you wish to fork or contribute back, here's a quick runthrough:

This repository contains both qsolve the binary and qsolve the library it depends on. The only logic in the binary is command line logic; all actual functionality should live in the library.

There are moderately comprehensive integration, unit and doctests that can be run with cargo test. Additionally, there are a few benchmarks using the criterion benchmark engine that can be run with cargo bench. In general, changes should be neutral or positive in that benchmark (for example, a change to use the bitvec package to implement the data structures in src/datastructure.rs was abandoned because cargo bench showed it was a regression).

Installing the command-line executable

Adding qsolve library as a dependency

Adding `qsolve` library as a dependency