+STARTUP: overview hidestars logdone

+COLUMNS: %38ITEM(Details) %7TODO(To Do) %TAGS(Context)

+OPTIONS: tags:t timestamp:t todo:t TeX:t LaTeX:t

+OPTIONS: @:t ::t |:t ^:t f:t

+LANGUAGE: en

+TITLE: Cryptator

[[https://opensource.org/licenses/BSD-3-Clause][https://img.shields.io/badge/License-BSD%203--Clause-blue.svg]]

[[https://github.com/arnaud-m/cryptator/actions/workflows/CryptatorTest.yml][file:https://github.com/arnaud-m/cryptator/actions/workflows/CryptatorTest.yml/badge.svg]]

Cryptator is a cryptarithm solver using [[https://en.wikipedia.org/wiki/Constraint_programming][Constraint Programming]].\ It is based on [[https://github.com/chocoteam/choco-solver][choco-solver]] which is an open-source Java library for Constraint Programming.

It is described in the [[file:pdf/jfpc2023.pdf][white paper]] (in French) published at the conference [[https://pfia23.icube.unistra.fr/conferences/jfpc/index.html][JFPC 2023]].

• About cryptarithms [[https://en.wikipedia.org/wiki/Verbal_arithmetic][Cryptarithm]], or alphametic, is a type of mathematical game consisting of a mathematical equation among unknown numbers, whose digits are represented by letters of the alphabet.

  • [[http://www.cadaeic.net/alphas.htm][An Alphametic Page]], Mike Keith - a must for alphametic lovers.
  • [[http://cryptarithms.awardspace.us/][Cryptarithms Online]], Jorge A. C. B. Soares - it contains the Sphinx collection, links, books.
  • [[http://www.tkcs-collins.com/truman/alphamet/alphamet.shtml][Alphametic Puzzles]], Truman Collins - he has solvers and even generators.
  • [[https://www.math.uni-bielefeld.de/~sillke/PUZZLES/ALPHAMETIC/][Alphametics]], Torsten Sillke - collection, variants, references, and links.
  • You can also browse our [[file:src/main/cryptarithms/][collection of cryptarithms]].

• Download and Installation

  In the following, we distinguish two usages:

  • as a standalone application: the jar file includes all required dependencies,
  • as a library: the jar file excludes all dependencies.

** Prerequisites This project works on 32 bits and 64 bits environment and requires:

• JDK 11+
• Maven 3+

** As a stand-alone application

This project uses the Cross-platform Maven build system. : mvn clean package or to skip unit tests : mvn clean package -DskipTests=true

The jar file contains all required dependencies. The next step is simply to run the console application. : java -cp target/cryptator-*-with-dependencies.jar cryptator.Cryptator send+more=money

There are three console applications and the links below point to demonstration scripts.

• solve a cryptarithm with [[file:src/main/shell/demo-solve.sh][Cryptator]].
• generate cryptarithms with [[file:src/main/shell/demo-generate.sh][Cryptagen]] (see the [[file:src/main/shell/demo-generate-output.md][demo output]]).

• play the game with [[file:src/main/shell/demo-play.sh][Cryptamancer]].

  Execute the main class without argument to display the help message. ** As a library

  The jar file does not contains any dependencies, as of being used as a dependency of another application. The next step is to add the jar file to your classpath of your application and also add the required dependencies.

*** Inside a maven project

First, you must build from source and install it into your local .m2 repository.
: mvn install

Then, you only have to edit your pom.xml to declare the following library dependency:

+BEGIN_EXAMPLE

+END_EXAMPLE

** Integration tests The tests solve around 150 cryptarithms. By default, the tests are not executed by the regular maven lifecycle test execution. Indeed, their names are outside of the standard maven test runner nomenclature.

Just include it manually by feeding it as a parameter to the runner.

: mvn test -Dtest=ExtensiveTesting

• Contributing

Please read [[CONTRIBUTING.md][CONTRIBUTING.md]] for details on our how you can become a contributor and the process for submitting pull requests to us.

• Versioning

This project makes use of [[http://semver.org/][SemVer]] for versioning. A list of existing versions can be found in the [[https://github.com/arnaud-m/cryptator/releases][project's releases]].

• Authors

See [[AUTHORS][AUTHORS]] and [[CONTRIBUTORS][CONTRIBUTORS]] files.

• License

This project is licensed under the [[https://opensource.org/licenses/BSD-3-Clause/][3-Clause BSD License]] - see the [[LICENSE][LICENSE]] file for details.