los.1

.\" Automatically generated by Pandoc 3.1.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "" "" "" "" ""
.hy
.SH Lights out solver
.PP
CLI program created in Rust to solve Lights out
puzzle (https://mathworld.wolfram.com/LightsOutPuzzle.html).
.PP
It finds the minimal solution and you aswell run in simulation mode to
check that the board is going to look after a number of steps.
## Usage/Examples of flags
.SS Help
.PP
In order to read the documentation use \f[V]--help\f[R]
.IP
.nf
\f[C]
$ los --help
Lights Out Puzzle Solver 1.3.0
With the given input of on node it will output the order to toggle the lights to solve the puzzle

USAGE:
    los [OPTIONS] [--] [lights]...

ARGS:
    <lights>...    Indexes of the active lights (range from 1 to [cols]*[rows])

OPTIONS:
    -c, --cols <cols>            The number of columns [default: 3]
    -d, --display <mode>         Sets the way you display the results [default: draw] [possible
                                 values: simple, draw, all]
    -h, --help                   Print help information
    -i, --input <mode>           Changes where the first index is located in the matrix (eg: bl =
                                 bottom left) [default: bl] [possible values: tl, tr, bl, br]
    -r, --rows <rows>            The number of rows [default: 3]
    -s, --simulate <steps>...    Run a simulation with the given input
    -v, --verbose                Enable the debug logs
    -V, --version                Print version information
\f[R]
.fi
.PP
By default you just give the position of the lights that are on and in
response you get what lights you need to toggle.
.IP
.nf
\f[C]
$ los 7 9 1 3
#·#
·0·
#·#
\f[R]
.fi
.SS Simulation
.PP
In order to run a simulation just use \f[V]-s\f[R] in this case the `#'
character represents a light on.
.IP
.nf
\f[C]
$ los -s 1 2 3
···
###
·#·
\f[R]
.fi
.SS Size
.PP
To change the size of the board just set the number of columns or rows
using the \f[V]-c\f[R] and \f[V]-r\f[R] flag
.IP
.nf
\f[C]
$ los -c 4 -r 4

0123
4··5
6789
····
\f[R]
.fi
.SS Input mode
.PP
The input mode tells the origin of the indices so we can tell where to
start counting.
In this case there are 4 possible values: tl, tr, bl and br.
Each one of them telling if the first index is at the top left, top
right and so on.
.PP
Example of the indices for the different modes
.IP
.nf
\f[C]
tl
123
456
789 

tr
321 
654
987

bl
789
456
123

br
987
654
321
\f[R]
.fi
.PP
In this case the default value is \f[V]bl\f[R] (bottom left) it\[cq]s
done like that you can easily input a 3x3 board using just your num pad.
.SS Display
.PP
You can get the solution of the puzzle in 2 ways as a list of indices or
as a drawn matrix where the numbers tell the order to trigger the lights
and \f[V]#\f[R] is an on light and \f[V]·\f[R] an off light.
.SS Verbose
Note that you can also enable verbose mode with the \f[V]-v\f[R] flag
$ los -v 7 9 1 3
.IP
.nf
\f[C]
2022-06-02T09:16:28.556Z INFO [los] Verbose mode enabled
2022-06-02T09:16:28.556Z DEBUG [lights_out_solver::program] Input mode: \[dq]bl\[dq]
2022-06-02T09:16:28.557Z DEBUG [lights_out_solver::program] Active indices: [6, 8, 0, 2]
2022-06-02T09:16:28.557Z DEBUG [lights_out_solver::program] Rows: 3
2022-06-02T09:16:28.558Z DEBUG [lights_out_solver::program] Cols: 3
2022-06-02T09:16:28.558Z DEBUG [lights_out_solver::program] Searching for solution ...
2022-06-02T09:16:28.559Z DEBUG [lights_out_solver::program] Final solution: Some([4])
2022-06-02T09:16:28.559Z DEBUG [lights_out_solver::program] Draw mode: draw

#·#
·0·
#·#
\f[R]
.fi
And you can aswell use \f[V]-v\f[R] to see the board after each step in
the simulation
$ lights_out_solver -v -s 1 2 3
.IP
.nf
\f[C]
2022-06-02T09:19:55.664Z INFO [los] Verbose mode enabled
2022-06-02T09:19:55.665Z DEBUG [lights_out_solver::program] Input mode: \[dq]bl\[dq]
2022-06-02T09:19:55.665Z DEBUG [lights_out_solver::program] Active indices: []
2022-06-02T09:19:55.666Z DEBUG [lights_out_solver::program] Rows: 3
2022-06-02T09:19:55.666Z DEBUG [lights_out_solver::program] Cols: 3
2022-06-02T09:19:55.667Z DEBUG [lights_out_solver::program] Board before the simulation:

···
···
···
2022-06-02T09:19:55.668Z DEBUG [lights_out_solver::program] Steps to simulate: [6, 7, 8]
2022-06-02T09:19:55.668Z DEBUG [lights_out_solver::program] Step 0:

···
#··
##·
2022-06-02T09:19:55.669Z DEBUG [lights_out_solver::program] Step 1:

···
##·
··#
2022-06-02T09:19:55.671Z DEBUG [lights_out_solver::program] Step 2:

···
###
·#·
2022-06-02T09:19:55.672Z DEBUG [lights_out_solver::program] Board after simulation:
···
###
·#·

···
###
·#·
\f[R]
.fi
.SS Run Locally
.PP
Clone the project
.IP
.nf
\f[C]
  git clone https://github.com/kikawet/lights_out_solver
\f[R]
.fi
.PP
Go to the project directory
.IP
.nf
\f[C]
  cd lights_out_solver
\f[R]
.fi
.PP
Install and run the project
.IP
.nf
\f[C]
  cargo run -- -h
\f[R]
.fi
.SS Running Tests
.PP
To run tests, run the following command
.IP
.nf
\f[C]
  cargo test
\f[R]
.fi
.SS License
.PP
MIT (https://choosealicense.com/licenses/mit/)
.SS Related
.PP
Release using github actions -
rust-build.action (https://github.com/rust-build/rust-build.action)
.PP
Alternative method to solve the puzzle using polinomials instead of
backtracking -
LightsOut.hh (https://www.keithschwarz.com/interesting/code/?dir=lights-out)
by Keith Schwarz (htiek\[at]cs.stanford.edu)