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 flags. A flag may or may not take a value. 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 flag does not require a value. However, the conjure modelling command takes a flag called --output-directory, which specifies the directory under which Conjure places its output files. This flag requires a value.

Flags 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 a long name for a flag, and -o is a short name for the same flag.

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.

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¶

Following is Conjure’s full help message, provided for reference.

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 specific command, pass the --help flag after the command name. For example: 'conjure translate-solution --help'

Common flags:
-?	--help	Display help message
-V	--version	Print 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=DIR	Output directory. Generated models will be saved here. Default value: 'conjure-output'
	--numbering-start=INT	Starting value to output files. Default value: 1
	--smart-filenames	Use "smart names" for the models. Turned off by default. Caution: With this flag, Conjure will use the answers when producing a filename. It will ignore the order of questions. This will become a problem if anything other than 'f' is used for questions.
	--log-level=LOGLEVEL	Log level.
	--verbose-trail	Whether to generate verbose trails or not.
	--rewrites-trail	Whether to generate trails about the applied rewritings or not.
	--log-rule-fails	Generate logs for rule failures. (Caution: these can be a lot!)
	--log-rule-successes	Generate logs for rule applications.
	--log-rule-attempts	Generate logs for rule attempts. (Caution: these can be a lot!)
	--log-choices	Store the choices in a way that can be reused be by -al
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
Model generation:
-q	--strategy-q=STRATEGY	Strategy to use when selecting the next question to answer. Options: f (for first), i (for interactive), r (for random), x (for all). The letter a (for auto) can be prepended to automatically skip when there is only one option at any point. Default value: f
-a	--strategy-a=STRATEGY	Strategy to use when selecting an answer. Same options as strategy-q. Moreover, c (for compact) can be used to pick the most 'compact' option at every decision point. And, s (for sparse) can be used to pick the most 'sparse' option at every decision point. This can be particularly useful for --representations-givens l (for follow log) tries to pick the given choices as far as possible Default value: ai
	--representations=STRATEGY	Strategy to use when choosing a representation. Default value: same as --strategy-a
	--representations-finds=STRATEGY	Strategy to use when choosing a representation for a decision variable. Default value: same as --representations
	--representations-givens=STRATEGY	Strategy to use when choosing a representation for a parameter. Default value: c (for compact)
	--representations-auxiliaries=STRATEGY	Strategy to use when choosing a representation for an auxiliary variable. Default value: same as --representations
	--representations-quantifieds=STRATEGY	Strategy to use when choosing a representation for a quantified variable. Default value: same as --representations
	--representations-cuts=STRATEGY	Strategy to use when choosing a representation for cuts in 'branching on'. Default value: same as --representations-cuts
	--channelling	Whether to produce channelled models or not. Can be true or false. (true by default) false: Do not produce channelled models. true : Produce channelled models.
	--representation-levels	Whether to use built-in precedence levels when choosing representations. These levels are used to cut down the number of generated models. Can be true or false. (true by default)
	--seed=INT	The seed for the random number generator.
	--limit-models=INT	Maximum number of models to generate.
	--choices=FILE	Choices to use if possible for -al can either be a eprime file (created by --logChoices), or a json file
General:
	--limit-time=INT	Time limit in seconds (real time).

conjure translate-parameter [OPTIONS]
Refinement of parameter files written in Essence for a particular Essence' model. The model needs to be generated by Conjure.

Flags:
	--eprime=FILE	An Essence' model generated by Conjure.
	--essence-param=FILE	An Essence parameter for the original problem specification.
	--eprime-param=FILE	An Essence' parameter matching the Essence' model. This field is optional. By default, its value will be 'foo.eprime-param' if the Essence parameter file is named 'foo.param'
Logging & Output:
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (real time).

conjure translate-solution [OPTIONS]
Translation of solutions back to Essence.

Flags:
	--eprime=FILE	An Essence' model generated by Conjure.
	--essence-param=FILE	An Essence parameter for the original problem specification. This field is optional.
	--eprime-solution=FILE	An Essence' solution for the corresponding Essence' model.
	--essence-solution=FILE	An Essence solution for the original problem specification. This field is optional. By default, its value will be the value of --eprime-solution, with all extensions dropped the extension '.solution' is added instead.
Logging & Output:
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (real time).

conjure validate-solution [OPTIONS]
Validating a solution.

Flags:
	--essence=FILE	A problem specification in Essence
	--param=FILE	An Essence parameter. This field is optional.
	--solution=FILE	An Essence solution.
Logging & Output:
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (real time).

conjure solve [OPTIONS] ESSENCE_FILE [PARAMETER_FILE(s)]
This is a combined mode, and it is available for convenience. It runs Conjure in the modelling mode followed by parameter translation if required, then Savile Row + Minion to solve, and then solution translation.

General:
	--validate-solutions	Enable/disable solution validation. Off by default.
	--limit-time=INT	Time limit in seconds (real time).
	--number-of-solutions=ITEM	Number of solutions to find. Pass the string "all" to enumerate all solutions. Default: 1
	--copy-solutions	Whether to place a copy of solution(s) next to the Essence file or not. Default: on
Logging & Output:
-o	--output-directory=DIR	Output directory. Generated models will be saved here. Default value: 'conjure-output'
	--numbering-start=INT	Starting value to output files. Default value: 1
	--smart-filenames	Use "smart names" for the models. Turned off by default. Caution: With this flag, Conjure will use the answers when producing a filename. It will ignore the order of questions. This will become a problem if anything other than 'f' is used for questions.
	--log-level=LOGLEVEL	Log level.
	--verbose-trail	Whether to generate verbose trails or not.
	--rewrites-trail	Whether to generate trails about the applied rewritings or not.
	--log-rule-fails	Generate logs for rule failures. (Caution: these can be a lot!)
	--log-rule-successes	Generate logs for rule applications.
	--log-rule-attempts	Generate logs for rule attempts. (Caution: these can be a lot!)
	--log-choices	Store the choices in a way that can be reused be by -al
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
Model generation:
-q	--strategy-q=STRATEGY	Strategy to use when selecting the next question to answer. Options: f (for first), i (for interactive), r (for random), x (for all). The letter a (for auto) can be prepended to automatically skip when there is only one option at any point. Default value: f
-a	--strategy-a=STRATEGY	Strategy to use when selecting an answer. Same options as strategy-q. Moreover, c (for compact) can be used to pick the most 'compact' option at every decision point. And, s (for sparse) can be used to pick the most 'sparse' option at every decision point. This can be particularly useful for --representations-givens l (for follow log) tries to pick the given choices as far as possible Default value: c
	--representations=STRATEGY	Strategy to use when choosing a representation. Default value: same as --strategy-a
	--representations-finds=STRATEGY	Strategy to use when choosing a representation for a decision variable. Default value: same as --representations
	--representations-givens=STRATEGY	Strategy to use when choosing a representation for a parameter. Default value: c (for compact)
	--representations-auxiliaries=STRATEGY	Strategy to use when choosing a representation for an auxiliary variable. Default value: same as --representations
	--representations-quantifieds=STRATEGY	Strategy to use when choosing a representation for a quantified variable. Default value: same as --representations
	--representations-cuts=STRATEGY	Strategy to use when choosing a representation for cuts in 'branching on'. Default value: same as --representations-cuts
	--channelling	Whether to produce channelled models or not. Can be true or false. (true by default) false: Do not produce channelled models. true : Produce channelled models.
	--representation-levels	Whether to use built-in precedence levels when choosing representations. These levels are used to cut down the number of generated models. Can be true or false. (true by default)
	--seed=INT	The seed for the random number generator.
	--limit-models=INT	Maximum number of models to generate.
	--use-existing-models=FILE	Takes paths of Essence' models generated beforehand. If given, Conjure will skip the modelling phase and use the existing models for solving.
Options for other tools:
	--savilerow-options=ITEM	Options to be passed to Savile Row.
	--solver-options=ITEM	Options to be passed to the backend solver.
	--solver=ITEM	Backend solver to use. 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-quantified	Whether to normalise the names of quantified variables or not. Off by default.
	--remove-unused	Whether to remove unused declarations or not. Off by default.
Logging & Output:
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (real time).

conjure diff [OPTIONS] FILE FILE
Diff on two Essence files. Works on models, parameters, and solutions.

Logging & Output:
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (real time).

conjure type-check [OPTIONS] ESSENCE_FILE
Type-checking a single Essence file.

Logging & Output:
	--log-level=LOGLEVEL	Log level.
General:
	--limit-time=INT	Time limit in seconds (real time).

conjure split [OPTIONS] ESSENCE_FILE
Split an Essence file to various smaller files. Useful for testing.

Logging & Output:
-o	--output-directory=DIR	Output directory. Generated models will be saved here. Default value: 'conjure-output'
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (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_FILE	Output JSON file. By default, its value will be 'foo.essence-json' if the Essence file is named 'foo.essence'
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (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=FILE	Output file path.
	--log-level=LOGLEVEL	Log level.
	--output-format=FORMAT	Conjure'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=INT	Line width to use during pretty printing. Default: 120
General:
	--limit-time=INT	Time limit in seconds (real time).