this repo has no description
dekker.one
1.. _ch-first-steps:
2
3First steps with MiniZinc
4=========================
5
6We recommend using the bundled binary distribution of MiniZinc introduced in :numref:`ch-installation`. It contains the MiniZinc IDE, the MiniZinc compiler, and several pre-configured solvers so you can get started straight away.
7
8This section introduces the MiniZinc IDE and the command line tool ``minizinc`` using some very basic examples. This should be enough to get you started with the MiniZinc tutorial in :numref:`part-tutorial` (in fact, you only need to be able to use one of the two, for instance just stick to the IDE if you are not comfortable with command line tools, or just use the ``minizinc`` command if you suffer from fear of mice).
9
10The MiniZinc IDE
11----------------
12
13The MiniZinc IDE provides a simple interface to most of MiniZinc's functionality. It lets you edit model and data files, solve them with any of the solvers supported by MiniZinc, run debugging and profiling tools, and submit solutions to online courses (such as the MiniZinc Coursera courses).
14
15When you open the MiniZinc IDE for the first time, it will ask you whether you want to be notified when an update is available. If you installed the IDE from sources, it may next ask you to locate your installation of the MiniZinc compiler. Please refer to :numref:`sec-ide-config` for more details on this.
16
17The IDE will then greet you with the *MiniZinc Playground*, a window that will look like this:
18
19.. image:: figures/mzn-ide-playground.jpg
20 :width: 600px
21
22You can start writing your first MiniZinc model! Let's try something very simple:
23
24.. image:: figures/mzn-ide-playground2.jpg
25 :width: 600px
26
27In order to solve the model, you click on the *Run* button in the toolbar, or use the keyboard shortcut *Ctrl+R* (or *command+R* on macOS):
28
29.. image:: figures/mzn-ide-playground3.jpg
30 :width: 600px
31
32As you can see, an output window pops up that displays a solution to the problem you entered.
33Let us now try a model that requires some additional data.
34
35.. image:: figures/mzn-ide-playground4.jpg
36 :width: 600px
37
38When you run this model, the IDE will ask you to enter a value for the parameter *n*:
39
40.. image:: figures/mzn-ide-playground-param.jpg
41 :width: 300px
42
43After entering, for example, the value 4 and clicking *Ok*, the solver will execute the model for *n=4*:
44
45.. image:: figures/mzn-ide-playground5.jpg
46 :width: 600px
47
48Alternatively, data can also come from a file. Let's create a new file with the data and save it as ``data.dzn``:
49
50.. image:: figures/mzn-ide-data.jpg
51 :width: 600px
52
53When you now go back to the *Playground* tab and click *Run*, the IDE will give you the option to select a data file:
54
55.. image:: figures/mzn-ide-select-data.jpg
56 :width: 300px
57
58Click on the ``data.dzn`` entry, then on *Ok*, and the model will be run with the given data file:
59
60.. image:: figures/mzn-ide-playground-data.jpg
61 :width: 600px
62
63Of course you can save your model to a file, and load it from a file, and the editor supports the usual functionality.
64
65If you want to know more about the MiniZinc IDE, continue reading from :numref:`ch-ide`.
66
67The MiniZinc command line tool
68------------------------------
69
70The MiniZinc command line tool, ``minizinc``, combines the functionality of the MiniZinc compiler, different solver interfaces, and the MiniZinc output processor. After installing MiniZinc from the bundled binary distribution, you may have to set up your ``PATH`` in order to use the command line tool (see :numref:`ch-installation`).
71
72Let's assume we have a file ``model.mzn`` with the following contents:
73
74::
75
76 var 1..3: x;
77 var 1..3: y;
78 constraint x+y > 3;
79 solve satisfy;
80
81You can simply invoke ``minizinc`` on that file to solve the model and produce some output:
82
83.. code-block:: none
84
85 $ minizinc model.mzn
86 x = 3;
87 y = 1;
88 ----------
89 $
90
91If you have a model that requires a data file (like the one we used in the IDE example above), you pass both files to ``minizinc``:
92
93.. code-block:: none
94
95 $ minizinc model.mzn data.dzn
96 x = 5;
97 y = 1;
98 ----------
99 $
100
101The ``minizinc`` tool supports numerous command line options. One of the most useful options is ``-a``, which switches between *one solution* mode and *all solutions* mode. For example, for the first model above, it would result in the following output:
102
103.. code-block:: none
104
105 $ minizinc -a model.mzn
106 x = 3;
107 y = 1;
108 ----------
109 x = 2;
110 y = 2;
111 ----------
112 x = 3;
113 y = 2;
114 ----------
115 x = 1;
116 y = 3;
117 ----------
118 x = 2;
119 y = 3;
120 ----------
121 x = 3;
122 y = 3;
123 ----------
124 ==========
125 $
126
127To learn more about the ``minizinc`` command, explore the output of ``minizinc --help`` or continue reading in :numref:`ch-cmdline`.