SICStus Prolog: MiniZinc Exported Predicates

10.48.3.2 Exported Predicates

The following predicates all take as (optional) argument a list Options, which can be used to change the default behavior of the execution. This list may contain zero or more of the following:

data_file(MznDatFile)

where MznDatFile must be a MiniZinc data file. Means that MznDatFile is passed to mzn2fzn through the --data option.

parameters(ListOfParDef)

where ListOfParDef is a list of elements of the form Id=Value where Id is a MiniZinc identifier and Value is a MiniZinc value. Means that all elements are written to a temporary file, which is passed to mzn2fzn through the --data option.

post(Boolean)

where Boolean must be true or false. If true (the default), then the constraints of the MiniZinc program are posted directly and a separate call to fzn_post/1 (see FlatZinc Exported Predicates) is not necessary. (Only usable with mzn_load_file/3 and mzn_load_model/3.)

search(Method) since release 4.3

where Method must be one of the atoms bab and restart. Tells the solver which optimization algorithm to use: branch-and-bound (the default), or to restart the search each time a new solution is found. (Only usable with mzn_run_file/2 and mzn_run_model/2.)

solutions(NumberOfSolutions)

where NumberOfSolutions must be an integer greater than zero or the atom all. Describes the number of solutions to search for, default is 1. (Only usable with mzn_run_file/2 and mzn_run_model/2.)

output(File)

where File must be the name of a writable file. Causes any output written on the current output stream to be directed to File. (Only usable with mzn_run_file/2 and mzn_run_model/2.)

fzn_file(File) since release 4.2.3

where File must be the name of a writable file. The translated FlatZinc program will be written to the given file. Otherwise, a temporary file will be used and erased afterwards.

ozn_file(File) since release 4.2.3

where File must be the name of a writable file. The MiniZinc output commands will be written to the given file. Otherwise, a temporary file will be used and erased afterwards.

optimise(Boolean) since release 4.2.3

optimize(Boolean) since release 4.2.3

where Boolean must be true (the default) or false. If false, then --no-optimise is passed to mzn2fzn.

statistics(Boolean)

where Boolean must be true or false (default). If true, then the following statistics are written on the current output stream (see the built-in statistics/[0,2] and fd_statistics/[0,2] of library(clpfd) for more detailed information on their meaning):

runtime: Total running time (milliseconds), including parsing the FlatZinc program.
solvetime: Running time (milliseconds) for posting the constraints and performing the search.
solutions: The number of solutions found.
constraints: The number of constraints created.
backtracks: The number of times a contradiction was found by a domain being wiped out, or by a global constraint signalling failure.
prunings: The number of times a domain was pruned.

(Only usable with mzn_run_file/2 and mzn_run_model/2.)

timeout(Time)

where Time should be an integer greater than zero. Stops the computation if it has not finished before Time milliseconds has elapsed. In any event, the best solution found so far is reported. Measuring starts after the call to mzn2fzn has finished. (Only usable with mzn_run_file/2 and mzn_run_model/2.)

variables(ListOfVarDef)

where ListOfVarDef is a list of elements of the form Id=Var where Id is a MiniZinc identifier and Var is a Prolog variable. Means that Var is unified with the value of Id after the MiniZinc program is loaded. (Only usable with mzn_load_file/3 and mzn_load_model/3).

The first two predicates can be used to run a MiniZinc program in one go.

mzn_run_file(+MznFile)

mzn_run_file(+MznFile, +Options)

MznFile is a MiniZinc program file and Options is a list of options as described above. Runs the MiniZinc program on MznFile, and writes the result onto the file given in the option/1 option if given, or onto the current output stream otherwise. This is done by first calling mzn2fzn, and then interpreting its output with fzn_run_stream/[1,2] (see FlatZinc Exported Predicates). Fails if the constraints of the MiniZinc program are inconsistent.

Exceptions:

Exceptions related to the opening of MznFile for reading.
A system error if mzn2fzn is unsuccessful. This error will include any information produced by mzn2fzn on its standard error stream.
A type error if the number of solutions to search for is not greater than zero nor the atom all.
Exceptions regarding errors in MznFile (see Zinc Errors) although these are most probably already handled by mzn2fzn.

mzn_run_model(+MznModel)

mzn_run_model(+MznModel, +Options)

MznModel is a MiniZinc program specified by a list of strings as explained below and Options is a list of options as described above. Runs the MiniZinc program MznModel, and writes the result onto the file given in the option/1 option if given, or onto the current output stream otherwise. This is done by first calling mzn2fzn and interpreting its output with fzn_run_stream/[1,2] (see FlatZinc Exported Predicates). The MiniZinc program specification MznModel must be a list of strings (list of character codes) where each element must specify one line of the MiniZinc program. For example, a MiniZinc program for the N Queens problem can be specified as follows:

NQueens = ["int: n;",
           "array [1..n] of var 1..n: q;",
           "constraint forall (i in 1..n, j in i+1..n)",
               "(q[i] != q[j] /\\",
                "q[i] + i != q[j] + j /\\",
                "q[i] - i != q[j] - j);",
           "solve satisfy;",
           "output [\"A solution to the \", show(n),",
           "\" Queens problem: \", show(q), \"\\n\"];"]

Note that backslashes and double quotes must be escaped with an additional backslash.

Exceptions:

A system error if mzn2fzn is unsuccessful. This error will include any information produced by mzn2fzn on its standard error stream.
A type error if the number of solutions to search for is not greater than zero nor the atom all.
Exceptions regarding errors in MznModel (see Zinc Errors) although these are most probably already handled by mzn2fzn.

Consider the following MiniZinc program for solving the N Queens problem located in library('zinc/examples/queen.mzn'):

queen.mzn

int: n;

array [1..n] of var 1..n: q;

constraint
    forall (i in 1..n, j in i+1..n) (
        q[i] != q[j] /\
        q[i] + i != q[j] + j /\
        q[i] - i != q[j] - j
    );

solve satisfy;

output ["A solution to the ", show(n), " Queens problem: ", show(q), "\n"];

Consider now the following goal at the Prolog top level:

| ?- mzn_run_file(library('zinc/examples/queen'), 
                  [data_file(library('zinc/examples/queen4.dat'))]).

Since library('zinc/examples/queen4.dat') contains the single line

n = 4;

the following is written on the current output stream:

A solution to the 4 Queens problem: [2, 4, 1, 3]
----------

The initialization n = 4 can also be passed using the parameter/1 option. So the following goal is equivalent to the one above:

| ?- mzn_run_file(library('zinc/examples/queen'), [parameters([n=4])]).

Finally, the following goal finds all solutions to the 4 Queens problem:

| ?- mzn_run_file(library('zinc/examples/queen'), 
                  [parameters([n=4]), solutions(all)]).

Given this goal, the following is written on the current output stream:

A solution to the 4 Queens problem: [2, 4, 1, 3]
----------
A solution to the 4 Queens problem: [3, 1, 4, 2]
----------
==========

The next two predicates can be used to construct a FlatZinc state (see FlatZinc Exported Predicates).

mzn_load_file(+MznFile, -FznState)

mzn_load_file(+MznFile, +Options, -FznState)

MznFile is a MiniZinc program file and Options is a list of options as described above. Initializes a FlatZinc state FznState with respect to MznFile. May fail if post(true) and the constraints are inconsistent.

Exceptions:

Exceptions related to the opening of MznFile for reading.
A system error if mzn2fzn is unsuccessful. This error will include any information produced by mzn2fzn on its standard error stream.
An existence error if an Id of the variables/1 option is not an identifier of FznState.
Exceptions regarding errors in MznFile (see Zinc Errors) although these are most probably already handled by mzn2fzn.

mzn_load_model(+MznModel, -FznState)

mzn_load_model(+MznModel, +Options, -FznState)

MznModel is a MiniZinc program specified by a list of strings as explained for mzn_run_model/[1,2] above and Options is a list of options as described above. Initializes a FlatZinc state FznState with respect to MznModel. May fail if post(true) and the constraints are inconsistent.

Exceptions:

A system error if mzn2fzn is unsuccessful. This error will include any information produced by mzn2fzn on its standard error stream.
An existence error if an Id of the variables/1 option is not an identifier of FznState.
Exceptions regarding errors in MznModel (see Zinc Errors) although these are most probably already handled by mzn2fzn.

The following Prolog goal constructs a FlatZinc state representing the 4 Queens problem:

| ?- mzn_load_file(library('zinc/examples/queen'), 
                   [parameters([n=4])], Queen4State).

See FlatZinc Exported Predicates for more information on FlatZinc states and how they can be queried. A very useful option to mzn_load_file/3 and mzn_load_model/3 is the variables/1 option, which can be used to unify values of MiniZinc identifiers with Prolog variables (this option can be used in place of several calls to fzn_identifier/3). For example, the following goal posts an additional symmetry breaking constraint and labels the variables using a Prolog goal that finds all remaining solutions to the 4 Queens problem:

| ?- mzn_load_file(library('zinc/examples/queen'), 
                   [parameters([n=4]), variables([q=Q])],
                   Queen4State),
     Q = [Q1, Q2|_], Q1 #< Q2,
     findall(_, (labeling([], Q), fzn_output(Queen4State)), _).

Given this goal, the following is written on the current output stream:

q = array1d(1..4, [2, 4, 1, 3]);
----------

The final predicate can be used to translate a MiniZinc file to a FlatZinc by a direct call to mzn2fzn.

mzn_to_fzn(+MznFile, +FznFile)

mzn_to_fzn(+MznFile, +Options, +FznFile)

MznFile is a MiniZinc program file and Options is a list of options as described above. Calls mzn2fzn, whose result is written to FznFile.

Exceptions:

Exceptions related to the opening of MznFile for reading as well as the opening of FznFile for writing.
A system error if mzn2fzn is unsuccessful. This error will include any information produced by mzn2fzn on its standard error stream.
Exceptions regarding errors in MznFile (see Zinc Errors) although these are most probably already handled by mzn2fzn.

Send feedback on this subject.