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: | ||
--help | Display help message | |
--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 | Where to save generated models. Default value: 'conjure-output' |
--numbering-start=INT | Starting value for output files. Default value: 1 | |
--smart-filenames | Use "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=LOGLEVEL | Log level. | |
--verbose-trail | Generate verbose trails. | |
--rewrites-trail | Generate trails about the applied rewritings. | |
--log-rule-fails | Generate logs for rule failures. (Caution: can be a lot!) | |
--log-rule-successes | Generate logs for rule applications. | |
--log-rule-attempts | Generate logs for rule attempts. (Caution: can be a lot!) | |
--log-choices | Store the choices in a way that can be reused by -al | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
Model generation: | ||
--responses=ITEM | A comma separated list of integers. If provided, these will be used as the answers during interactive model generation instead of prompting the user. | |
--estimate-number-of-models | Calculate (a lower bound on) the number of models, instead of running the usual modelling mode. | |
-q | --strategy-q=STRATEGY | Strategy 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=STRATEGY | Strategy 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=STRATEGY | Strategy for choosing a representation. Default value: same as --strategy-a | |
--representations-finds=STRATEGY | Strategy for choosing a representation for a decision variable. Default value: same as --representations | |
--representations-givens=STRATEGY | Strategy for choosing a representation for a parameter. Default value: s (for sparse) | |
--representations-auxiliaries=STRATEGY | Strategy for choosing a representation for an auxiliary variable. Default value: same as --representations | |
--representations-quantifieds=STRATEGY | Strategy for choosing a representation for a quantified variable. Default value: same as --representations | |
--representations-cuts=STRATEGY | Strategy for choosing a representation for cuts in 'branching on'. Default value: same as --representations | |
--channelling | Whether to produce channelled models (true by default). | |
--representation-levels | Whether to use built-in precedence levels when choosing representations. Used to cut down the number of generated models. Default: true | |
--seed=INT | Random number generator seed. | |
--limit-models=INT | Maximum number of models to generate. | |
--choices=FILE | Choices to use for -al, either an eprime file (created by --log-choices), or a json file. | |
General: | ||
--limit-time=INT | Limit 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=ESSENCE_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. Default is 'foo.eprime-param' if the Essence parameter file is named 'foo.param'. | |
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit in seconds of real time. | |
conjure translate-solution [OPTIONS] | ||
Translation of solutions back to Essence. | ||
Flags: | ||
--eprime=FILE | An Essence' model generated by Conjure. Mandatory. | |
--essence-param=FILE | An Essence parameter for the original problem specification. Mandatory. | |
--eprime-solution=FILE | An Essence' solution for the corresponding Essence' model. | |
--essence-solution=FILE | An 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=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit in seconds of real time. | |
conjure validate-solution [OPTIONS] | ||
Validating a solution. | ||
Flags: | ||
--essence=ESSENCE_FILE | Problem specification in Essence. | |
--param=FILE | Essence parameter file. | |
--solution=FILE | Essence solution. | |
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit 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-solutions | Enable solution validation. | |
--limit-time=INT | Limit in seconds of real time. | |
--cgroups | Setup and use cgroups when solving with Savile Row. | |
--number-of-solutions=ITEM | Number of solutions to find; "all" enumerates 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 | Where to save generated models. Default value: 'conjure-output' |
--numbering-start=INT | Starting value for output files. Default value: 1 | |
--smart-filenames | Use "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. | |
--solutions-in-one-file | Place all solutions in a single file instead of generating a separate file per solution. Off by default. | |
--log-level=LOGLEVEL | Log level. | |
--verbose-trail | Generate verbose trails. | |
--rewrites-trail | Generate trails about the applied rewritings. | |
--log-rule-fails | Generate logs for rule failures. (Caution: can be a lot!) | |
--log-rule-successes | Generate logs for rule applications. | |
--log-rule-attempts | Generate logs for rule attempts. (Caution: can be a lot!) | |
--log-choices | Store the choices in a way that can be reused by -al | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
Model generation: | ||
--responses=ITEM | A 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=STRATEGY | Strategy 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=STRATEGY | Strategy 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=STRATEGY | Strategy for choosing a representation. Default value: same as --strategy-a | |
--representations-finds=STRATEGY | Strategy for choosing a representation for a decision variable. Default value: same as --representations | |
--representations-givens=STRATEGY | Strategy for choosing a representation for a parameter. Default value: s (for sparse) | |
--representations-auxiliaries=STRATEGY | Strategy for choosing a representation for an auxiliary variable. Default value: same as --representations | |
--representations-quantifieds=STRATEGY | Strategy for choosing a representation for a quantified variable. Default value: same as --representations | |
--representations-cuts=STRATEGY | Strategy for choosing a representation for cuts in 'branching on'. Default value: same as --representations | |
--channelling | Whether to produce channelled models (true by default). | |
--representation-levels | Whether to use built-in precedence levels when choosing representations. Used to cut down the number of generated models. Default: true | |
--seed=INT | Random number generator seed. | |
--limit-models=INT | Maximum number of models to generate. | |
--use-existing-models=FILE | File names of Essence' models generated beforehand. If given, Conjure skips the modelling phase and uses the existing models for solving. The models should be inside the output directory (See -o). | |
Options for other tools: | ||
--savilerow-options=ITEM | Options passed to Savile Row. | |
--solver-options=ITEM | Options passed to the backend solver. | |
--solver=ITEM | Backend solver. Possible values: - minion (CP solver) - gecode (CP solver) - chuffed (CP solver) - glucose (SAT solver) - glucose-syrup (SAT solver) - lingeling (SAT solver) - minisat (SAT solver) - bc_minisat_all (AllSAT solver, only works with --number-of-solutions=all) - nbc_minisat_all (AllSAT solver, only works with --number-of-solutions=all) - open-wbo (MaxSAT solver, only works with optimisation problems) Default: minion | |
conjure ide [OPTIONS] ESSENCE_FILE | ||
IDE support features for Conjure. Not intended for direct use. | ||
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit in seconds of real time. | |
IDE Features: | ||
--dump-declarations | Print information about top level declarations. | |
--dump-representations | List the available representations for decision variables and parameters. | |
conjure pretty [OPTIONS] ESSENCE_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 | Normalise the names of quantified variables. | |
--remove-unused | Remove unused declarations. | |
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit 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=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit in seconds of 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 | Limit 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=DIR | Where to save generated models. Default value: 'conjure-output' |
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit 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_FILE | Output JSON file. Default is 'foo.essence-json' if the Essence file is named 'foo.essence' | |
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit 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=FILE | Output file path. | |
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. plain : default binary: can be read by Conjure json : use to avoid parsing | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
Integer bounds: | ||
--MININT=INT | The minimum integer value for the parameter values. Default: 0 | |
--MAXINT=INT | The maximum integer value for the parameter values. Default: 100 | |
General: | ||
--limit-time=INT | Limit 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=FILE | Output file path. | |
--log-level=LOGLEVEL | Log level. | |
--log-rule-successes | Generate logs for rule applications. | |
--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). |