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 by `runLastMinizincJSON` for serialization of input instance Hashable Input -- required by `simpleMiniZinc` to create a somewhat unique filepath data Output = Output {y :: Int} deriving (Show, Generic) instance FromJSON Output -- required by `runLastMinizincJSON` for deserialization of output 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). A more-general function named `runMinizincJSON` allows to stream results iteratively has the solver progresses. This function is more complicated than `runLastMinizincJSON` has it takes a callback to consume an output and control whether to continue reading inputs or not (i.e., a coroutine) plus some initial state that is carried over (a bit like a fold). Luckily, we provide two coroutines `keepLast` and `collectResults` for some typical use cases. # 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. A function named `cleanTmpFile` will remove the `.json` disk file for a given pair of MiniZinc and input objects. # Development ## Testing We use [Hedgehog](https://hedgehog.qa/) to test the overall system at once rather than having individual tests for the internal parser and other files. Test cases are in `.hs` files under the `test` directory whereas the `.mzn` models are in the `models` directory. We use a naming nomenclature to help organize what files require what input/output types: `test{inputtype}_{testnum}.mzn` where `inputtype` pertains to the haskell Input/Output types and `testnum` pertains to the test number. Thus: all `testnum` are unique and are groupable by `inputtype`. # Misc. The author of this package is not affiliated with MiniZinc. See also: [https://www.minizinc.org/](https://www.minizinc.org/).