minizinc-process
================

MiniZinc is a language and a toolchain to solve discrete optimization problems.
This package offers wrappers around the `minizinc` executable to pass inputs and outputs.

Assume that a primitive MiniZinc model is available at the path `models/example001.mzn`.

```minizinc
0..100: x;
var int: y;
constraint x < y;
```

This model expects `x` as an Int and decides `y` as an Int if a solution is
found. Ideally we would like to use minizinc and this model like a function of
type `Int -> IO (Maybe Int)` function in Haskell.
This package provides building blocks to create such a mapping.

# Implementation

This package relies on JSON support for MiniZinc by using JSON as an
intermediary representation. On the Haskell side we picked the popular `aeson`
package for serializing values.

MiniZinc input binds names to variables, hence the `Int -> IO (Maybe Int)`
example above is insufficient: inputs and outputs need to translate to JSON
`Object` constructor of [Aeson's Value type](https://hackage.haskell.org/package/aeson-1.1.1.0/docs/Data-Aeson.html#t:Value).

# Example Use

The `runLastMinizincJSON` function requires some configuration object to
provide parameters like the solver backing MiniZinc, the timeout, where to
store MiniZinc data files. The `simpleMiniZinc` function provides a smart
constructor for building such an environment.

```haskell
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE TypeApplications #-}

module Main where

import Data.Aeson
import Data.Hashable
import GHC.Generics
import Process.Minizinc
import Process.Minizinc.Inspect

data Input = Input {x :: Int}
  deriving (Generic)

instance ToJSON Input -- required for `runLastMinizincJSON`

instance Hashable Input -- required for `runLastMinizincJSON`

data Output = Output {y :: Int}
  deriving (Show, Generic)

instance FromJSON Output -- required for `runLastMinizincJSON`

main :: IO ()
main = do
  inspect "models/example001.mzn" >>= print
  let mzn = simpleMiniZinc @Input @Output "models/example001.mzn" 1000 Gecode
  let problem = Input 10
  runLastMinizincJSON mzn problem >>= print
```

The `@Input` and `@Output` syntax allow to pass type parameters to
`simpleMiniZinc`, this style is optional but helps the GHC compiler inference
(in our example, this type application is the only indication needed to tell
the compiler to deserialize `Output` objects).

# Usage in a project

In a typical project, you will have fixed models and varying inputs.
That is, you would like to carry the models along with the code (e.g., a web
application or gRPC server using minizinc in the background) in a same
repository as your Haskell code. One option is to leverage the support of cabal
[data-files](https://www.haskell.org/cabal/users-guide/developing-packages.html#accessing-data-files-from-package-code).

You will still need some mapping functions to translate between domain objects
like `User` into the JSON values that MiniZinc requires: objects do not map
well with relations. We may consider compile-time helpers like TemplateHaskell,
but at this time it would not be immediately feasible. Be at peace with this.

For now, the implementation leverages file-system to pass the JSON object to
MiniZinc, this design means you should pay attention to disk usage and maybe
clean the clutter.

# Misc.

The author of this package is not affiliated with MiniZinc.
See also: [https://www.minizinc.org/](https://www.minizinc.org/).