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). |