-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.html
350 lines (312 loc) · 14.6 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>README</title>
<!-- 2014-09-30 Tue 20:02 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="generator" content="Org-mode" />
<meta name="author" content="torsten" />
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
.title { text-align: center; }
.todo { font-family: monospace; color: red; }
.done { color: green; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.right { margin-left: auto; margin-right: 0px; text-align: right; }
.left { margin-left: 0px; margin-right: auto; text-align: left; }
.center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #ccc;
box-shadow: 3px 3px 3px #eee;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: visible;
padding-top: 1.2em;
}
pre.src:before {
display: none;
position: absolute;
background-color: white;
top: -10px;
right: 10px;
padding: 3px;
border: 1px solid black;
}
pre.src:hover:before { display: inline;}
pre.src-sh:before { content: 'sh'; }
pre.src-bash:before { content: 'sh'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-R:before { content: 'R'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-java:before { content: 'Java'; }
pre.src-sql:before { content: 'SQL'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.right { text-align: center; }
th.left { text-align: center; }
th.center { text-align: center; }
td.right { text-align: right; }
td.left { text-align: left; }
td.center { text-align: center; }
dt { font-weight: bold; }
.footpara:nth-child(2) { display: inline; }
.footpara { display: block; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
/*]]>*/-->
</style>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2013 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
</head>
<body>
<div id="content">
<h1 class="title">README</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">1. clojure2minizinc</a>
<ul>
<li><a href="#sec-1-1">1.1. Summary</a></li>
<li><a href="#sec-1-2">1.2. Usage: A Minimal Example</a></li>
<li><a href="#sec-1-3">1.3. Installation</a>
<ul>
<li><a href="#sec-1-3-1">1.3.1. Installation of MiniZinc tools</a></li>
<li><a href="#sec-1-3-2">1.3.2. Installation of clojure2minizinc</a></li>
</ul>
</li>
<li><a href="#sec-1-4">1.4. Documentation</a></li>
<li><a href="#sec-1-5">1.5. Related Work</a>
<ul>
<li><a href="#sec-1-5-1">1.5.1. Clojure: core.logic</a></li>
<li><a href="#sec-1-5-2">1.5.2. C++: libmzn</a></li>
</ul>
</li>
<li><a href="#sec-1-6">1.6. Contribute</a></li>
<li><a href="#sec-1-7">1.7. License</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="outline-container-sec-1" class="outline-2">
<h2 id="sec-1"><span class="section-number-2">1</span> clojure2minizinc</h2>
<div class="outline-text-2" id="text-1">
</div><div id="outline-container-sec-1-1" class="outline-3">
<h3 id="sec-1-1"><span class="section-number-3">1.1</span> Summary</h3>
<div class="outline-text-3" id="text-1-1">
<p>
<i>clojure2minizinc</i> provides an interface between <a href="http://www.minizinc.org/software.html">state-of-the-art constraint solvers</a> (via <i>MiniZinc</i>) and a very high-level programming language with excellent abstraction capabilities, <a href="http://clojure.org">Clojure</a>. The clojure2minizinc user models in Clojure constraint satisfaction or optimisation problems over Boolean, integer, real number, and/or set variables. clojure2minizinc translates them into MiniZinc, they are solved in the background by a compatible solver, and the result is read back into Clojure. clojure2minizinc code can be very similar to the corresponding MiniZinc code, but in addition the full power of Clojure is at hand.
</p>
</div>
</div>
<div id="outline-container-sec-1-2" class="outline-3">
<h3 id="sec-1-2"><span class="section-number-3">1.2</span> Usage: A Minimal Example</h3>
<div class="outline-text-3" id="text-1-2">
<p>
The following model declares two decision variables <code>a</code> and <code>b</code>, both with the domain <i>[-1 .. 1]</i>, and constraints them to be different.
</p>
<div class="org-src-container">
<pre class="src src-clojure">(<span style="color: #a020f0;">ns</span> <span style="color: #228b22;">clojure2minizinc.examples</span>
(<span style="color: #008b8b;">:require</span> [<span style="color: #228b22;">clojure2minizinc.core</span> <span style="color: #008b8b;">:as</span> mz]))
(<span style="color: #228b22;">mz</span>/minizinc
(<span style="color: #228b22;">mz</span>/clj2mnz
(<span style="color: #a020f0;">let</span> [a (<span style="color: #228b22;">mz</span>/variable (<span style="color: #228b22;">mz</span>/-- -1 1))
b (<span style="color: #228b22;">mz</span>/variable (<span style="color: #228b22;">mz</span>/-- -1 1))]
(<span style="color: #228b22;">mz</span>/constraint (<span style="color: #228b22;">mz</span>/!= a b))
(<span style="color: #228b22;">mz</span>/solve <span style="color: #008b8b;">:satisfy</span>)
(<span style="color: #228b22;">mz</span>/output-map {<span style="color: #008b8b;">:a</span> a <span style="color: #008b8b;">:b</span> b})))
<span style="color: #008b8b;">:num-solutions</span> 3)
</pre>
</div>
<p>
The model asks for three solutions, and the default solver outputs the following.
</p>
<p>
<code>; => ({:a 0, :b -1} {:a 1, :b -1} {:a -1, :b 0})</code>
</p>
</div>
</div>
<div id="outline-container-sec-1-3" class="outline-3">
<h3 id="sec-1-3"><span class="section-number-3">1.3</span> Installation</h3>
<div class="outline-text-3" id="text-1-3">
<p>
See the [[./doc/installation][installation notes]
</p>
</div>
<div id="outline-container-sec-1-3-1" class="outline-4">
<h4 id="sec-1-3-1"><span class="section-number-4">1.3.1</span> Installation of MiniZinc tools</h4>
<div class="outline-text-4" id="text-1-3-1">
<ul class="org-ul">
<li>Install the <a href="http://www.minizinc.org/g12distrib.html">G12 MiniZinc Distribution</a> (includes software that translates MiniZinc to the intermediate simpler format FlatZinc, which is understood by 3rd-party solvers, but also ready-to-use solvers)
<ul class="org-ul">
<li>Follow the installation instructions and do not forget to run the install script as described
</li>
<li>The default clojure2minizinc settings expect executables <code>minizinc</code> and its friends are in your <a href="http://en.wikipedia.org/wiki/PATH_(variable)">PATH</a>
</li>
</ul>
</li>
<li>Optionally, install additional solvers. For example, see FlatZinc implementations at <a href="http://www.minizinc.org/software.html">http://www.minizinc.org/software.html</a>
</li>
</ul>
</div>
</div>
<div id="outline-container-sec-1-3-2" class="outline-4">
<h4 id="sec-1-3-2"><span class="section-number-4">1.3.2</span> Installation of clojure2minizinc</h4>
<div class="outline-text-4" id="text-1-3-2">
<p>
Add this <a href="https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md">Leiningen</a> dependency to your project:
</p>
<div class="org-src-container">
<pre class="src src-clojure">[<span style="color: #228b22;">minizinc</span>/clojure2minizinc <span style="color: #8b2252;">"0.2.0"</span>]
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-sec-1-4" class="outline-3">
<h3 id="sec-1-4"><span class="section-number-3">1.4</span> Documentation</h3>
<div class="outline-text-3" id="text-1-4">
<p>
clojure2minizinc comes with a <a href="http://tanders.github.io/clojure2minizinc/tutorial.html">tutorial</a> and <a href="http://tanders.github.io/clojure2minizinc/reference/clojure2minizinc.core.html">reference documentation</a>, which are both part of the source tree.
</p>
</div>
</div>
<div id="outline-container-sec-1-5" class="outline-3">
<h3 id="sec-1-5"><span class="section-number-3">1.5</span> Related Work</h3>
<div class="outline-text-3" id="text-1-5">
</div><div id="outline-container-sec-1-5-1" class="outline-4">
<h4 id="sec-1-5-1"><span class="section-number-4">1.5.1</span> Clojure: core.logic</h4>
<div class="outline-text-4" id="text-1-5-1">
<p>
In the Clojure community there already exists an interest in Constraint Programming (and the related Logic Programming paradigm), and solvers have been developed for Clojure.
</p>
<p>
<a href="https://github.com/clojure/core.logic">core.logic</a> implements logic programming facilities from scratch directly in Clojure. More specifically, it implements <a href="http://minikanren.org">miniKanren</a>. It also implements some of its extensions, e.g., <a href="https://github.com/calvis/cKanren">cKanren</a> for Constraint Logic Programming.
</p>
<p>
By contrast, clojure2minizinc provides an interface to a range of existing state-of-the-art constraint solvers. Unlike core.logic, it does not support Logic Programming (e.g., it does not provide unification of arbitrary terms). However, Constraint Programming is supported in a clearly more mature way by MiniZinc, and clojure2minizinc inherits its capabilities. MiniZinc supports more variable domains than core.logic (Booleans, integers, floats, and set of integers), more constraints (including more <a href="http://www.minizinc.org/downloads/doc-1.6/mzn-globals.html">global constraints</a>), reified constraints (i.e., the truth value of constraints can in turn be constrained by logic relations such as implication or equivalence), and optimisation support.
</p>
<p>
Perhaps most importantly, MiniZinc's 3rd-party solvers implement highly efficient search strategies developed by the <a href="http://www.a4cp.org/events/cp-conference-series">Constraint Programming community</a>, which clearly <a href="https://github.com/clojure/core.logic/wiki/External-solvers">outperform core.logic</a>. The MiniZinc to FlatZinc transformation adds a <a href="http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.91.271&rep=rep1&type=pdf">certain overhead</a>, but this overhead is small and can be neglected, in particular for more complex constraint problems. The translation from clojure2minizinc to MiniZinc is so simple that its overhead is even less and can also be neglected.
</p>
<p>
(<b>TODO: reading results back into Clojure possibly causes another overhead – more careful testing and improving of performance necessary, once clojure2minizinc is somewhat more mature</b>)
</p>
</div>
</div>
<div id="outline-container-sec-1-5-2" class="outline-4">
<h4 id="sec-1-5-2"><span class="section-number-4">1.5.2</span> C++: libmzn</h4>
<div class="outline-text-4" id="text-1-5-2">
<p>
A project with similar goals as clojure2minizinc is <a href="http://cp2013.a4cp.org/sites/default/files/uploads/cospel2013_submission_7.pdf">libmzn</a>, which provides a C++ interface to MiniZinc. It is planned to be released as part of MiniZinc 2.0.
</p>
</div>
</div>
</div>
<div id="outline-container-sec-1-6" class="outline-3">
<h3 id="sec-1-6"><span class="section-number-3">1.6</span> Contribute</h3>
<div class="outline-text-3" id="text-1-6">
<p>
Most clojure2minizinc functions simply generate a string with the corresponding MiniZinc code. So, this library is very easy to extend to support by and by the full feature set of MiniZinc, and also MiniZinc extensions proposed by various research projects.
</p>
<p>
Your contribution is welcome!
</p>
<p>
For posting ideas, discussions and bug reports please use GitHub issues.
</p>
</div>
</div>
<div id="outline-container-sec-1-7" class="outline-3">
<h3 id="sec-1-7"><span class="section-number-3">1.7</span> License</h3>
<div class="outline-text-3" id="text-1-7">
<p>
Distributed under the GNU General Public License.
</p>
<p>
Copyright © 2014 Torsten Anders
</p>
</div>
</div>
</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: torsten</p>
<p class="date">Created: 2014-09-30 Tue 20:02</p>
<p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 24.3.50.2 (<a href="http://orgmode.org">Org</a> mode 8.2.7b)</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>