Command Line Interface

Conjure supports a number of commands. A command is provided as the first argument to Conjure on the command line. It is followed by a number of mandatory arguments (if any) depending on the command, and a number of optional arguments.

Some command line arguments to Conjure are positional, for example the command name. Another example of positional arguments is the path to a file required by the conjure pretty command. This argument can just be provided after the command name, like: conjure pretty myfile.essence.

Non-positional arguments are provided using options. Some options require an additional value to be provided. Other options are flags and do not expect additional values. For example the conjure pretty command takes a flag called --remove-unused, which removes unused decision variables from the model before pretty printing it. This option is a flag that takes no values. However, the conjure modelling command takes an option called --output-directory, which specifies the directory under which Conjure places its output files. This option requires a value.

Options can have short or long names. Following the common convention, short option names are preceded by a single dash and long options names are preceded by two dashes. For example --output-directory is a long name for an option, and -o is a short name for the same option.

The general form of a Conjure run is as follows: conjure [COMMAND] ... [OPTIONS].

Following is the list of primary commands provided by Conjure. They can be used to generate Essence’ models from Essence files, translate parameter files and solution files for a specific Essence’ model, and more.

modelling
The main act. Given a problem specification in Essence, produce constraint programming models in Essence’.
translate-parameter
Refinement of parameter files written in Essence for a particular Essence’ model. The Essence’ model needs to be generated by Conjure.
translate-solution
Translation of solutions back to Essence.
validate-solution
Validating a solution.
solve
This is a combined mode, and it is available for convenience. It runs conjure in the modelling mode followed by parameter refinement if required, then Savile Row + Minion to solve, and then solution translation.

If no primary command is provided, modelling is assumed.

Conjure also supports a few additional commands on top of the primary commands listed above. These commands are not required for the normal operation of the tool. They are implemented to aid development and testing.

pretty
Pretty print as Essence file to stdout. This mode can be used to view a binary Essence file in textual form.
diff
Diff on two Essence files. Works on models, parameters, and solutions.
type-check
Type-checking a single Essence file.
split
Split an Essence files to various smaller files. Useful for testing.
symmetry-detection
Dump some JSON to be used as input to ferret for symmetry detection.
parameter-generator
Generate an Essence model describing the instances of the problem class defined in the input Essence model. An error will be printed if the model has infinitely many instances.

Commands typically take additional arguments. Each command provides a separate help message. To see the command specific help message, run: conjure COMMAND --help.

Help output

The following is Conjure’s full help message for each command, provided for reference. These messages may change between releases of Conjure.

Conjure: The Automated Constraint Modelling Tool
 
conjure [COMMAND] ... [OPTIONS]
The command line interface of Conjure takes a command name as the first argument followed by more arguments depending on the command.
This help text gives a list of the available commands.
For details of a command, pass the --help flag after the command name.
For example: 'conjure translate-solution --help'
 
Common flags:
 --helpDisplay help message
 --versionPrint version information
 
conjure [modelling] [OPTIONS] ESSENCE_FILE
The main act. Given a problem specification in Essence, produce constraint programming models in Essence'.
 
Logging & Output:
-o--output-directory=DIRWhere to save generated models.
Default value: 'conjure-output'
 --numbering-start=INTStarting value for output files.
Default value: 1
 --smart-filenamesUse "smart names" for models.
Directs Conjure to use the answers when producing a filename and to ignore the order of questions. Only useful if 'f' is used for questions.
 --log-level=LOGLEVELLog level.
 --verbose-trailGenerate verbose trails.
 --rewrites-trailGenerate trails about the applied rewritings.
 --log-rule-failsGenerate logs for rule failures. (Caution: can be a lot!)
 --log-rule-successesGenerate logs for rule applications.
 --log-rule-attemptsGenerate logs for rule attempts. (Caution: can be a lot!)
 --log-choicesStore the choices in a way that can be reused by -al
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
Model generation:
 --responses=ITEMA comma separated list of integers.
If provided, these will be used as the answers during interactive model generation instead of prompting the user.
-q--strategy-q=STRATEGYStrategy for selecting the next question to answer. Options: f (for first), i (for interactive), r (for random), x (for all). Prepend a (for auto) to automatically skip when there is only one option at any point.
Default value: f
-a--strategy-a=STRATEGYStrategy for selecting an answer. Same options as strategy-q.
c picks the most 'compact' option at every decision point.
s picks the 'sparsest' option at every decision point: useful for --representations-givens
l (for follow log) tries to pick given choices as far as possible
Default value: ai
 --representations=STRATEGYStrategy for choosing a representation.
Default value: same as --strategy-a
 --representations-finds=STRATEGYStrategy for choosing a representation for a decision variable.
Default value: same as --representations
 --representations-givens=STRATEGYStrategy for choosing a representation for a parameter.
Default value: s (for sparse)
 --representations-auxiliaries=STRATEGYStrategy for choosing a representation for an auxiliary variable.
Default value: same as --representations
 --representations-quantifieds=STRATEGYStrategy for choosing a representation for a quantified variable.
Default value: same as --representations
 --representations-cuts=STRATEGYStrategy for choosing a representation for cuts in 'branching on'.
Default value: same as --representations-cuts
 --channellingWhether to produce channelled models (true by default).
 --representation-levelsWhether to use built-in precedence levels when choosing representations. Used to cut down the number of generated models.
Default: true
 --seed=INTRandom number generator seed.
 --limit-models=INTMaximum number of models to generate.
 --choices=FILEChoices to use for -al, either an eprime file (created by --log-choices), or a json file.
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure translate-parameter [OPTIONS]
Refinement of Essence parameter files for a particular Essence' model.
The model needs to be generated by Conjure.
 
Flags:
 --eprime=FILEAn Essence' model generated by Conjure.
 --essence-param=FILEAn Essence parameter for the original problem specification.
 --eprime-param=FILEAn Essence' parameter matching the Essence' model.
Default is 'foo.eprime-param' if the Essence parameter file is named 'foo.param'.
Logging & Output:
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure translate-solution [OPTIONS]
Translation of solutions back to Essence.
 
Flags:
 --eprime=FILEAn Essence' model generated by Conjure.
Mandatory.
 --essence-param=FILEAn Essence parameter for the original problem specification.
Mandatory.
 --eprime-solution=FILEAn Essence' solution for the corresponding Essence' model.
 --essence-solution=FILEAn Essence solution for the original problem specification.
By default, its value is the value of --eprime-solution with extensions replaced by '.solution'.
Logging & Output:
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure validate-solution [OPTIONS]
Validating a solution.
 
Flags:
 --essence=FILEProblem specification in Essence.
 --param=FILEEssence parameter file.
 --solution=FILEEssence solution.
Logging & Output:
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure solve [OPTIONS] ESSENCE_FILE [PARAMETER_FILE(s)]
A combined mode for convenience.
Runs Conjure in modelling mode followed by parameter translation if required, then Savile Row + Minion to solve, and then solution translation.
 
General:
 --validate-solutionsEnable solution validation.
 --limit-time=INTLimit in seconds of real time.
 --number-of-solutions=ITEMNumber of solutions to find; "all" enumerates all solutions.
Default: 1
 --copy-solutionsWhether to place a copy of solution(s) next to the Essence file or not.
Default: on
Logging & Output:
-o--output-directory=DIRWhere to save generated models.
Default value: 'conjure-output'
 --numbering-start=INTStarting value for output files.
Default value: 1
 --smart-filenamesUse "smart names" for models.
Directs Conjure to use the answers when producing a filename and to ignore the order of questions. Only useful if 'f' is used for questions.
 --log-level=LOGLEVELLog level.
 --verbose-trailGenerate verbose trails.
 --rewrites-trailGenerate trails about the applied rewritings.
 --log-rule-failsGenerate logs for rule failures. (Caution: can be a lot!)
 --log-rule-successesGenerate logs for rule applications.
 --log-rule-attemptsGenerate logs for rule attempts. (Caution: can be a lot!)
 --log-choicesStore the choices in a way that can be reused by -al
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
Model generation:
 --responses=ITEMA comma separated list of integers.
If provided, these will be used as the answers during interactive model generation instead of prompting the user.
-q--strategy-q=STRATEGYStrategy for selecting the next question to answer. Options: f (for first), i (for interactive), r (for random), x (for all). Prepend a (for auto) to automatically skip when there is only one option at any point.
Default value: f
-a--strategy-a=STRATEGYStrategy for selecting an answer. Same options as strategy-q.
c picks the most 'compact' option at every decision point.
s picks the 'sparsest' option at every decision point: useful for --representations-givens
l (for follow log) tries to pick given choices as far as possible
Default value: c
 --representations=STRATEGYStrategy for choosing a representation.
Default value: same as --strategy-a
 --representations-finds=STRATEGYStrategy for choosing a representation for a decision variable.
Default value: same as --representations
 --representations-givens=STRATEGYStrategy for choosing a representation for a parameter.
Default value: s (for sparse)
 --representations-auxiliaries=STRATEGYStrategy for choosing a representation for an auxiliary variable.
Default value: same as --representations
 --representations-quantifieds=STRATEGYStrategy for choosing a representation for a quantified variable.
Default value: same as --representations
 --representations-cuts=STRATEGYStrategy for choosing a representation for cuts in 'branching on'.
Default value: same as --representations-cuts
 --channellingWhether to produce channelled models (true by default).
 --representation-levelsWhether to use built-in precedence levels when choosing representations. Used to cut down the number of generated models.
Default: true
 --seed=INTRandom number generator seed.
 --limit-models=INTMaximum number of models to generate.
 --use-existing-models=FILEPaths of Essence' models generated beforehand. If given, Conjure skips the modelling phase and uses existing models for solving.
Options for other tools:
 --savilerow-options=ITEMOptions passed to Savile Row.
 --solver-options=ITEMOptions passed to the backend solver.
 --solver=ITEMBackend solver. Possible values: minion/lingeling/minisat
Default: minion
 
conjure pretty [OPTIONS] FILE
Pretty print as Essence file to stdout.
This mode can be used to view a binary Essence file in textual form.
 
Flags:
 --normalise-quantifiedNormalise the names of quantified variables.
 --remove-unusedRemove unused declarations.
Logging & Output:
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure diff [OPTIONS] FILE FILE
Diff on two Essence files. Works on models, parameters, and solutions.
 
Logging & Output:
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure type-check [OPTIONS] ESSENCE_FILE
Type-checking a single Essence file.
 
Logging & Output:
 --log-level=LOGLEVELLog level.
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure split [OPTIONS] ESSENCE_FILE
Split an Essence file to various smaller files. Useful for testing.
 
Logging & Output:
-o--output-directory=DIRWhere to save generated models.
Default value: 'conjure-output'
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure symmetry-detection [OPTIONS] ESSENCE_FILE
Dump some JSON to be used as input to ferret for symmetry detection.
 
Logging & Output:
 --json=JSON_FILEOutput JSON file.
Default is 'foo.essence-json'
if the Essence file is named 'foo.essence'
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure parameter-generator [OPTIONS] ESSENCE_FILE
Generate an Essence model describing the instances of the problem class defined in the input Essence model.
An error will be printed if the model has infinitely many instances.
 
Logging & Output:
 --essence-out=FILEOutput file path.
 --log-level=LOGLEVELLog level.
 --output-format=FORMATFormat to use for output.
plain : default
binary: can be read by Conjure
json : use to avoid parsing
 --line-width=INTLine width for pretty printing.
Default: 120
General:
 --limit-time=INTLimit in seconds of real time.
 
conjure model-strengthening [OPTIONS] ESSENCE_FILE
Strengthen an Essence model as described in "Reformulating Essence Specifications for Robustness",
which aims to make search faster.
 
Logging & Output:
 --essence-out=FILEOutput file path.
 --log-level=LOGLEVELLog level.
 --log-rule-successesGenerate logs for rule applications.
 --output-format=FORMATConjure's output can be in multiple formats.
plain : The default
binary: A binary encoding of the Essence output.
It can be read back in by Conjure.
json : A json encoding of the Essence output.
It can be used by other tools integrating with Conjure
in order to avoid having to parse textual Essence.
 --line-width=INTLine width to use during pretty printing.
Default: 120
General:
 --limit-time=INTTime limit in seconds (real time).