Package: hyperdock
HyperdockA simple framework for distributed hyperparameter optimization in Docker.What is Hyperdock?Hyperdock is a framework for hyperparameter search that can be used to optimized any target as long as that target can be run in a Docker container. That means that the target can be written in any language, use any framework or run on any operating system as long as it can be made into a Docker image.The figure below shows the Hyperdock system and its main components.TheHyperdock Web UIis the main interface for the end-users from where they can specifytrials(atarget Docker imageand the hyperparameter space to search over). All trials, their status and results are stored in aMongo database.TheHyperdock Supervisoris a background process that monitors all trials. It determines whatjobs(a specific hyperparameter combination) need to scheduled, which jobs have failed and should be restarted, and notifies users of results.TheHyperdock Workersdequeues jobs from thework queueand then evaluates thetarget imagewith these parameters. They continually send status updates to the database to notify the user of progress.The entire Hyperdock system can be distributed, i.e. Supervisor, Workers and WebUI need not run on the same host. They only need to be able to access the same Mongo database and the workers need to have access to any data required by the target image.Each program that should be optimized needs to have its own Docker image, thetarget image, that is setup to load the parameters and write progress reports. Parameters are available in the json file/hyperdock/params.json. Once the target image has evaluated the parameters it simply writes the loss to the file/hyperdock/loss.jsonwith the option of storing important files to/hyperdock/out. Logs from the target image are periodically tailed from the workers to the WebUI. More about how to write a target image can found below.How does Hyperdock work?Hyperdock supports grid search of parameters from lists and distributions. See thewikifor details on how to define the parameters space.Setting up HyperdockYou can either use the pre-built Docker images for Hyperdock or run the sub-systems directly on the host(s). Finally you can also use theDocker composefile to setup a single host Hyperdock environment useful for testing - this method is very quick way to get started.SupervisorTo start the Hyperdock Supervisor using the Docker image run the following command:dockerrun-it\--rm\--namehyperdock-supervisor\--linkhyperdock-mongo\erikgartner/hyperdock-supervisor:latest\--mongodbmongodb://hyperdock-mongo:27017/hyperdockOr run it on your host with Python >= 3.6 and install with pip:pipinstallhyperdock
hyperdock-supervisor--mongodbmongodb://localhost:27017/hyperdockOptions--mongo mongodb://localhost:27017/hyperdockURL to the Mongo databaseFor full arguments to the supervisor run:hyperdock-supervisor --help.WorkerTo start the Hyperdock Worker using the Docker image run the following command:dockerrun-it\--rm\-v/var/run/docker.sock:/var/run/docker.sock\--linkhyperdock-mongo\-v$(pwd):$(pwd)\erikgartner/hyperdock-worker:latest\--mongodbmongodb://hyperdock-mongo:27017/hyperdockOr run it on your host with Python >= 3.6 and install with pip:pipinstallhyperdock
hyperdock-worker--mongodbmongodb://localhost:27017/hyperdockOptions-v $(pwd):$(pwd)mirrors the path structure from the host in to  the Docker container. This is needed since the paths must be the the same when the worker starts the Target Image and mounts the data and results folders.-v /var/run/docker.sock:/var/run/docker.sockgives the Docker image access to control the outer Docker daemon. This is crucial for worker to start new containersOr run it on your host with Python 3.6 and install with pip:pipinstallhyperdock
hyperdock-worker--mongodbmongodb://localhost:27017/hyperdockFor full arguments to the worker run:hyperdock-worker --help.Note:That since the Hyperdock Worker needs to control Docker and access files on the host computer.WebUITo start the Hyperdock WebUI using the Docker image run the following command:dockerrun-it\--rm\--namehyperdock-webui\--linkhyperdock-mongo\-eROOT_URL=http://localhost:3000/\-eMONGO_URL=mongodb://hyperdock-mongo:27017/hyperdock\-p3000:3000\erikgartner/hyperdock-webui:latestOptions-e MONGO_URL=mongodb://hyperdock-mongo:27017/hyperdocksets the Mongo database-p 3000:3000publish the Web UI's http portOr run it on your host with Meteor:# Install Meteorcurlhttps://install.meteor.com/|sh# Go into the Web UI source foldercdweb/
meteornpminstall# Set Mongo Database URLexportMONGO_URL=mongodb://localhost:27017/hyperdock# Start WebUImeteorrunTarget ImageEach optimization target needs atarget image. This image can be dynamic (i.e. checkout the latest source from Github) but preferably should be reproducible, for example by always checking out a specific commit.When running the container the target should:Read the parametersEvaluate the target programWrite the loss / results and then exit (with error code 0).Communication between Hyperdock and the target program is handle through a few special files and folders that are mounted and populated by Hyperdock./hyperdock/loss.jsonwrite the loss here; format describedhereparams.jsonparameters for the run; format describedheregraphs.jsonoptional file, contains graphs for Web UI plots; format describedhereout/persistent folder, use this to write any other files to the result folder/dataa read only folder that contains any external data neededSee theDockfile templatefor an example. It is available as a Docker image namederikgartner/hyperdock-demo:latest. By default it outputs0as its loss but by setting the environment
variableFUNCTIONto a python expression (for examplea +  b) you can compute an arbitrary loss based on the Hyperdock parameters.Mongo DatabaseTo start a Mongo database you can use this simple Docker command or use any normal Mongo instance.# Starts mongo db, add --bind_ip_all to listen on all interfaces.dockerrun--namehyperdock-mongo-p27017:27017-dmongoDocker ComposeTo setup Hyperdock on a single host the Docker compose file is a very easy way to get started. Just set the marked line indocker-compose.ymlto a host directory that should contain data and results. Then simply run:docker-composeupDevelopingHyperdock welcomes new contributors and pull-requests, but please start by reading the contributionguidelines. If you don't know where to start, sending a message to contributors is a good start!Hyperdock usesPipenvto manage the Python version and the package dependencies. The WebUI is built usingMeteorwhich needs to be installed prior to development.Hyperdock usesTravisfor test monitoring, continuous integration and continuous deployment.TestingHyperdock usesnoseas the test runner for the Python package.Notethat the test machine needs a working Docker installation that doesn't require sudo. Always run the tests locally before pushing.# Install packages and development packages with the correct Python versionpipenvinstall-d# Run tests with nosenosetests-svFor the WebUI run:exportMONGO_URL=mongodb://localhost:27017/hyperdock

meteornpminstall
meteorrunLicenseCopyright 2018-2019 Erik GärtnerLicensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0CitingIf you use Hyperdock in your research please cite it as:@misc{hyperdock,
  author = {G{\"a}rtner, Erik},
  title = {Hyperdock},
  year = {2019},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/ErikGartner/Hyperdock}},
}