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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. | |
--responses-representation=ITEM | A comma separated list of variable name : integer pairs. If provided, these will be used as the answers during interactive model generation instead of prompting the user for the variable representation questions. See --dump-representations for a list of available representation options. | |
--estimate-number-of-models | Calculate (a lower bound on) the number of models, instead of running the usual modelling mode. | |
--portfolio=PORTFOLIO | Portfolio size. When it is set to N, Conjure will try to generate up to N models. | |
-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 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 | |
--follow-model=ITEM | Provide a Conjure-generated Essence Prime model to be used as a guide during model generation. Conjure will try to imitate the modelling decisions from this file. | |
--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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. | |
--graph-solver | Create input files for the Glasgow graph solver. | |
--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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. | |
--responses-representation=ITEM | A comma separated list of variable name : integer pairs. If provided, these will be used as the answers during interactive model generation instead of prompting the user for the variable representation questions. See --dump-representations for a list of available representation options. | |
--portfolio=PORTFOLIO | Portfolio size. When it is set to N, Conjure will try to generate up to N models. | |
-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 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 | |
--follow-model=ITEM | Provide a Conjure-generated Essence Prime model to be used as a guide during model generation. Conjure will try to imitate the modelling decisions from this file. | |
--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/plingeling/treengeling (SAT solver) - cadical (SAT solver) - kissat (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) - coin-or (MIP solver, implemented via MiniZinc) - cplex (MIP solver, implemented via MiniZinc) - boolector (SMT solver, supported logics: bv) - yices (SMT solver, supported logics: bv, lia, idl) - z3 (SMT solver, supported logics: bv, lia, nia, idl) Default: minion Default logic for SMT solvers is bitvector (bv). Append a dash and the name of a logic to the solver name to choose a different logic. For example yices-idl. | |
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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--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. | ||
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 | |
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit in seconds of real time. | |
conjure autoig [OPTIONS] ESSENCE_FILE OUTPUT_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. | ||
Flags: | ||
--generator-to-irace | Convert the givens in a hand written generator model to irace syntax. | |
--remove-aux | Remove lettings whose name start with Aux | |
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
--output-format=FORMAT | Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--line-width=INT | Line width for pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Limit in seconds of real time. | |
conjure boost [OPTIONS] ESSENCE_FILE | ||
Strengthen an Essence model as described in "Reformulating Essence Specifications for Robustness", which aims to make search faster. | ||
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
--log-rule-successes | Generate logs for rule applications. | |
--output-format=FORMAT | Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions jsonstream: same as JSON, except in one special case. when multiple solutions are saved in a single file as json, this mode prints one solution per line minizinc: minizinc format for data files, only used for solutions | |
--line-width=INT | Line width to use during pretty printing. Default: 120 | |
General: | ||
--limit-time=INT | Time limit in seconds (real time). | |
conjure tsdef [OPTIONS] | ||
Generate data type definitions in TypeScript. These can be used when interfacing with Conjure via JSON. | ||
Logging & Output: | ||
--log-level=LOGLEVEL | Log level. | |
General: | ||
--limit-time=INT | Limit in seconds of real time. |