nextmv Docs

Hop Packages

Hop Packages

Hop and Dash modules are divided into three top-level packages.

  • Models
  • Runners
  • Solvers (Hop) / Simulator (Dash)

Models

A model represents something to make a decision about. This might be a route for a bicycle courier, an assignment of compute jobs to machines on a network, or the price to bid in an auction.

models

Runners

A runner is the glue between input data, the model, and its environment. It reads data into a state structure defined by the modeler, runs a solver or simulator, and provides decisions as data.

In a bicycle routing problem, the input data contains the courier's current location and a set of locations to visit. The decision to visit the locations in a particular order is encoded by the runner directly as state data.

Runners make it easy to get decision data into models, test those models, and deploy them into different environments. Runners read in data described by a Go struct and output decisions, typically in JSON. We support a range of runners and are always growing our toolkit based on customer needs. Currently, we offer several pre-built options:

  • CLI Runner
  • Tests Runner
  • Lambda Runner
  • HTTP Runner

For more details on our runners, please refer to Model Runners. We add new runners all the time. If you don't see your deployment pattern, just ask us.

runners

Solvers & Simulators

Both Hop solvers and Dash simulators are state-based representations of a system of actors and actor decisions. Hop solvers search the space of feasible decisions and recommend a solution. They can maximize or minimize a user-defined objective, or merely satisfy a set of business rules. Dash simulators are event-based simulations of actor decisions. Modelers can customize solvers and simulators by creating their own actors and decision logic according to their use-case.

solver-simulator

Please visit Hop modules and Dash modules for a deeper dive into package structure for each tool.

Solvers

Hop solvers search the space of feasible decisions. They can maximize or minimize a user-defined objective, or merely satisfy a set of business rules.

The default Hop solver is a decision diagram optimizer. It works well on simple models defined as nothing more than states and transitions. For advanced usage, Hop provides interfaces for most of its components. These include such things as restrictors, queues, and searchers. Solver components can be swapped for canned or custom implementations. This lets modelers start simply and scale up their efforts when that becomes important.

Building & Testing

Hop requires at least Go 1.13. You should have the following environment variables set in your ~/.bashrc, ~/.zshrc or a similar configuration file.

export GOPATH=$(go env GOPATH)
export GOROOT=$(go env GOROOT)
export GOPRIVATE=github.com/nextmv-io/*
export PATH=$PATH:$GOPATH/bin

Note that if you installed Go directly from Golang, you do not need to add exports for GOPATH or GOROOT. If you installed go via Homebrew, you will need to add those lines to ~/.zshrc. If you were using bash previously, also be sure to source ~/.zshrc by running source ~/.zshrc.

Your ~/.gitconfig will probably work best if it directs git to clone repositories over ssh.

[url "git@github.com:"]
insteadOf = https://github.com/

If you are using the source distribution, you can build and test from the hop/ directory with the go command.

$ go build ./...
$ go test ./...
ok github.com/nextmv-io/code/hop 0.160s
ok github.com/nextmv-io/code/hop/model 0.176s
ok github.com/nextmv-io/code/hop/run 0.273s
ok github.com/nextmv-io/code/hop/run/cli 0.128s
ok github.com/nextmv-io/code/hop/run/http 0.183s
ok github.com/nextmv-io/code/hop/run/lambda 0.244s
ok github.com/nextmv-io/code/hop/solve 0.235s
ok github.com/nextmv-io/code/hop/solve/diagram 0.092s
ok github.com/nextmv-io/code/hop/solve/diagram/reduce 0.233s
ok github.com/nextmv-io/code/hop/solve/diagram/restrict 0.224s
ok github.com/nextmv-io/code/hop/solve/queue 0.256s
ok github.com/nextmv-io/code/hop/solve/search 0.259s
ok github.com/nextmv-io/code/hop/solve/stats 0.181s

Hop Releases

Like other Go modules, Hop uses semantic versioning. We tag releases from the master branch and add updates to the change log. Once we tag a new release, you can use go mod to require the new version of Hop in your own modules.

In this example replace <VERSION> with the semantic version you want to depend on (e.g. v0.2.3). Upgrading or downgrading your version of Hop works the same way.

go mod init
go get github.com/nextmv-io/code/hop@<VERSION>

To access Hop's package documentation, follow the instructions here.