Release v0.17.0

Release v0.17.0

Author: larsbeck

.github/workflows/go-lint.yml

@@ -16,4 +16,4 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v3
         with:
-          version: latest
+          version: v1.48.0

README.md

@@ -13,6 +13,10 @@ problems. Please find the following packages:
 Please visit the official [Go Package Docs][pkgsite] for documentation and
 testable examples.
 
+## Usage
+
+To run a decision automation problem with SDK you need the [Nextmv CLI][cli].
+
 ## Get started
 
 Please visit the [tour of SDK][tour] to get started with data store modeling.
@@ -25,16 +29,10 @@ Nextmv's SDK is meant to be used in Go projects. To download please run:
 go get github.com/nextmv-io/sdk
 ```
 
-## Usage
-
-To run a decision automation problem Nextmv's SDK requires specific plugins.
-Please contact [support][support] for details on installing plugins. They are
-not required to `build`.
-
 [pkgsite]: https://pkg.go.dev/github.com/nextmv-io/sdk
-[store]: ./store/
-[route]: ./route/
-[run]: ./run/
-[model]: ./model/
+[store]: ./store/README.md
+[route]: ./route/README.md
+[run]: ./run/README.md
+[model]: ./model/README.md
 [tour]: https://github.com/nextmv-io/tour
-[support]: https://www.nextmv.io/contact
+[cli]: https://docs.nextmv.io/development/cli

VERSION

@@ -1 +1 @@
-v0.16.0-dev.0-6
+v0.17.0

mip/connect.go

@@ -0,0 +1,31 @@
+package mip
+
+import (
+	"sync"
+
+	"github.com/nextmv-io/sdk/plugin"
+)
+
+const slug = "sdk"
+
+var connected bool
+
+var mtx sync.Mutex
+
+func connect() {
+	if connected {
+		return
+	}
+
+	mtx.Lock()
+	defer mtx.Unlock()
+
+	if connected {
+		return
+	}
+	connected = true
+
+	plugin.Connect(slug, "MIPNewSolveOptions", &newSolveOptions)
+	plugin.Connect(slug, "MIPNewModel", &newModel)
+	plugin.Connect(slug, "MIPNewSolver", &newSolver)
+}

mip/constraint.go

@@ -0,0 +1,63 @@
+package mip
+
+// Sense defines the constraint operator between the left-hand-side
+// and the right-hand-side.
+type Sense int64
+
+// Sense of a Constraint.
+const (
+	// LessThanOrEqual is used to define a less than or equal constraint
+	// 		c, _ := d.NewConstraint(mip.LessThanOrEqual, 123.4)
+	//
+	// 		c.NewTerm(1.0, x)  	 // results in 1.0 * x <= 123.4 in solver
+	LessThanOrEqual Sense = iota
+	// Equal is used to define an equality constraint
+	// 		c, _ := d.NewConstraint(mip.Equal, 123.4)
+	//
+	// 		c.NewTerm(1.0, x)  	 // results in 1.0 * x = 123.4 in solver
+	Equal
+	// GreaterThanOrEqual is used to define a greater or equal constraint
+	// 		c, _ := d.NewConstraint(mip.	GreaterThanOrEqual, 123.4)
+	//
+	// 		c.NewTerm(1.0, x)  	 // results in 1.0 * x >= 123.4 in solver
+	GreaterThanOrEqual
+)
+
+// Constraint specifies a relation between variables a solution has to comply
+// with. A constraint consists out of terms, a sense and a right hand side.
+//
+// For example:
+//
+//	2.5 * x + 3.5 * y <= 10.0
+//
+// The less than operator is the sense
+// The value 10.0 is the right hand side
+//
+//	2.5 * x and 3.5 * y are 2 terms in this example
+type Constraint interface {
+	// NewTerm adds a term to the invoking constraint, invoking this API
+	// multiple times for the same variable will take the sum of coefficients
+	// of earlier added terms for that variable
+	//
+	// 		d := mip.NewModel()
+	//
+	// 		x, _ := d.NewContinuousVar(10.0, 100.0)
+	//
+	// 		c, _ := d.NewConstraint(mip.LessThanOrEqual, 123.4)
+	//
+	// 		c.NewTerm(1.0, x)  	 // results in 1.0 * x <= 123.4 in solver
+	// 		c.NewTerm(2.0, x)    // results in 3.0 * x <= 123.4 in solver
+	NewTerm(coefficient float64, variable Var) Term
+	// RightHandSide returns the right-hand side of the invoking constraint.
+	RightHandSide() float64
+	// Sense returns the sense of the invoking constraint.
+	Sense() Sense
+	// Terms returns a copy slice of terms of the invoking constraint,
+	// each variable is reported once. If the same variable has been
+	// added multiple times the sum of coefficients is reported for that
+	// variable.
+	Terms() Terms
+}
+
+// Constraints slice of Constraint instances.
+type Constraints []Constraint

mip/doc.go

@@ -0,0 +1,38 @@
+/*
+Package mip provides a general interface for solving mixed integer linear
+optimization problems using a variety of back-end solvers. The base interface is
+the Model which is a collection of variables, constraints and an objective. The
+interface Solver is constructed by mip.NewSolver. The solver can be invoked
+using Solver.Solve and returns a Solution.
+
+A new Model is created:
+
+	d := mip.NewModel()
+
+Var instances are created and added to the model:
+
+	x, _ := d.NewContinuousVar(0.0, 100.0)
+	y, _ := d.NewIntegerVar(0, 100)
+
+Constraint instances are created and added to the model:
+
+	c1, _ := d.NewConstraint(mip.GreaterThanOrEqual, 1.0)
+	c1.NewTerm(-2.0, x)
+	c1.NewTerm(2.0, y)
+
+	c2, _ := d.NewConstraint(mip.LessThanOrEqual, 13.0)
+	c2.NewTerm(-8.0, x)
+	c2.NewTerm(10.0, y)
+
+The Objective is specified:
+
+	d.Objective().SetMaximize()
+	d.Objective().NewTerm(1.0, x)
+	d.Objective().NewTerm(1.0, y)
+
+A Solver is created and invoked to produce a Solution:
+
+	solver, _ := mip.NewSolver("backend_solver_identifier", mipModel)
+	solution, _ := solver.Solve(mip.DefaultSolverOptions())
+*/
+package mip

mip/example_constraint_test.go

@@ -0,0 +1,106 @@
+package mip_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/nextmv-io/sdk/mip"
+)
+
+func ExampleConstraint_greaterThanEqual() {
+	model := mip.NewModel()
+
+	c, _ := model.NewConstraint(mip.GreaterThanOrEqual, 1.0)
+
+	fmt.Println(c.Sense())
+	fmt.Println(c.RightHandSide())
+	// Output:
+	// 2
+	// 1
+}
+
+func ExampleConstraint_equal() {
+	model := mip.NewModel()
+
+	c, _ := model.NewConstraint(mip.Equal, 1.0)
+
+	fmt.Println(c.Sense())
+	fmt.Println(c.RightHandSide())
+	// Output:
+	// 1
+	// 1
+}
+
+func ExampleConstraint_lessThanOrEqual() {
+	model := mip.NewModel()
+
+	c, _ := model.NewConstraint(mip.LessThanOrEqual, 1.0)
+
+	fmt.Println(c.Sense())
+	fmt.Println(c.RightHandSide())
+	// Output:
+	// 0
+	// 1
+}
+
+func ExampleConstraint_terms() {
+	model := mip.NewModel()
+
+	v, _ := model.NewBinaryVar()
+	c, _ := model.NewConstraint(mip.Equal, 1.0)
+
+	t1 := c.NewTerm(1.0, v)
+	t2 := c.NewTerm(2.0, v)
+
+	fmt.Println(t1.Var().Index())
+	fmt.Println(t1.Coefficient())
+	fmt.Println(t2.Coefficient())
+	fmt.Println(len(c.Terms()))
+	fmt.Println(c.Terms()[0].Coefficient())
+	// Output:
+	// 0
+	// 1
+	// 2
+	// 1
+	// 3
+}
+
+func benchmarkNewConstraintNewTerms(nrTerms int, b *testing.B) {
+	model := mip.NewModel()
+	v, _ := model.NewContinuousVar(1.0, 2.0)
+
+	for i := 0; i < b.N; i++ {
+		c, _ := model.NewConstraint(mip.Equal, 1.0)
+		for i := 0; i < nrTerms; i++ {
+			c.NewTerm(1.0, v)
+		}
+	}
+}
+
+func BenchmarkNewConstraintNewTerms0(b *testing.B) {
+	benchmarkNewConstraintNewTerms(0, b)
+}
+
+func BenchmarkNewConstraintNewTerms1(b *testing.B) {
+	benchmarkNewConstraintNewTerms(1, b)
+}
+
+func BenchmarkNewConstraintNewTerms2(b *testing.B) {
+	benchmarkNewConstraintNewTerms(2, b)
+}
+
+func BenchmarkNewConstraintNewTerms4(b *testing.B) {
+	benchmarkNewConstraintNewTerms(4, b)
+}
+
+func BenchmarkNewConstraintNewTerms8(b *testing.B) {
+	benchmarkNewConstraintNewTerms(8, b)
+}
+
+func BenchmarkNewConstraintNewTerms16(b *testing.B) {
+	benchmarkNewConstraintNewTerms(16, b)
+}
+
+func BenchmarkNewConstraintNewTerms32(b *testing.B) {
+	benchmarkNewConstraintNewTerms(32, b)
+}

mip/example_model_test.go

@@ -0,0 +1,49 @@
+package mip_test
+
+import (
+	"fmt"
+
+	"github.com/nextmv-io/sdk/mip"
+)
+
+func ExampleModel_empty() {
+	model := mip.NewModel()
+
+	fmt.Println(len(model.Constraints()))
+	fmt.Println(len(model.Vars()))
+	fmt.Println(len(model.Objective().Terms()))
+	fmt.Println(model.Objective().IsMaximize())
+	// Output:
+	// 0
+	// 0
+	// 0
+	// false
+}
+
+func ExampleModel_queries() {
+	model := mip.NewModel()
+
+	_, err := model.NewBinaryVar()
+	if err != nil {
+		panic(err)
+	}
+	_, err = model.NewContinuousVar(1.0, 2.0)
+	if err != nil {
+		panic(err)
+	}
+	_, err = model.NewBinaryVar()
+	if err != nil {
+		panic(err)
+	}
+
+	_, err = model.NewConstraint(mip.Equal, 0.0)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(len(model.Vars()))
+	fmt.Println(len(model.Constraints()))
+	// Output:
+	// 3
+	// 1
+}