#+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]], and in the [[file:pdf/ictai2025.pdf][paper]] (in English) published at the conference [[https://easyconferences.eu/ictai2025/][ICTAI 2025]], which received the Best Paper Award..

* 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.
Each letter represents a digit, and the goal is to reconstruct the original arithmetic equation.

  - [[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 17+
  - Maven 3+
  - Cryptarithmetic Puzzle Solver in C (optional)
    - Download it from [[https://tamura70.gitlab.io/web-puzzle/cryptarithm/][Naoyuki Tamura Website]].
    - If compilation fails with recent GCC versions, compile with ~-std=gnu89~ to preserve compatibility with the old C syntax : ~make CFLAGS="-std=gnu89 -g -O~.
    - Note the installation path, as it will be used with the ~--crypt~ option of the solver.

** 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 two 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]]).

    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
 <dependency>
    <groupId>fr.univ-cotedazur</groupId>
    <artifactId>cryptator</artifactId>
    <version>2.0.0-SNAPSHOT</version>
 </dependency>
 #+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.