diff --git a/documentation/01-Prerequisites.md b/documentation/01-Prerequisites.md index f4abd295721..e23f45721a6 100644 --- a/documentation/01-Prerequisites.md +++ b/documentation/01-Prerequisites.md @@ -6,7 +6,7 @@ These are one-time setup instructions that should be executed prior to following - [Prerequisites for building and using MLOS](#prerequisites-for-building-and-using-mlos) - [Contents](#contents) - - [Cloning the repository](#clone-the-repository) + - [Clone the repository](#clone-the-repository) - [Python quickstart](#python-quickstart) - [Linux](#linux) - [Linux Distribution Requirements](#linux-distribution-requirements) @@ -21,11 +21,11 @@ These are one-time setup instructions that should be executed prior to following - [Step 1: Install Python](#step-1-install-python) - [Step 2: Install Docker on Windows](#step-2-install-docker-on-windows) - [Step 3: Install Windows Build Tools](#step-3-install-windows-build-tools) + - [Step 4: Build the Docker image](#step-4-build-the-docker-image) MLOS currently supports 64-bit Intel/AMD platforms, though ARM64 support is under development. It supports Windows and Linux environments. Below we provide instructions for each OS. - ## Clone the repository Make sure you have [git](https://git-scm.com/) installed and clone the repo: @@ -79,7 +79,6 @@ All of them require `git` and, of course, a Linux installation: > Other distros/versions may work, but are untested. - ### Option 1: Linux Docker Build Env #### Install Docker @@ -154,8 +153,6 @@ Follow the [Python Quickstart](#python-quickstart) above. MLOS is easiest to use on Windows 10, Version 1903 (March 2019) or newer. - - ### Step 1: Install Python Follow the [Python Quickstart](#python-quickstart) above. @@ -173,3 +170,7 @@ Download and install Visual Studio 2019 (free) Community Edition: Be sure to include support for .Net Core and C++. + +### Step 4: Build the Docker image + +The instructions for [building the docker image](#build-the-docker-image) are the same as for Linux. diff --git a/documentation/RepoOrganization.md b/documentation/RepoOrganization.md index 9779ffbf210..2aa310d59a4 100644 --- a/documentation/RepoOrganization.md +++ b/documentation/RepoOrganization.md @@ -9,7 +9,7 @@ Some notes on the directory layout organization in this repo. > Note: For this reason, `cmake` output is redirected to `out/cmake/{Release,Debug}/` instead. - [`source/`](../source/#mlos-github-tree-view) contains a directory for each component of MLOS, including unit test source code. - i.e. running `msbuild` or `make` in the `source/` directory will build (and generally analyze) all of the projects, but not execute their tests. - - [`source/Examples/`](../source/Examples/#mlos-github-tree-view) contains sample target codes to optimize with the other MLOS components and help describe the integration methods + - [`source/Examples/`](../source/Examples/) contains sample target codes to optimize with the other MLOS components and help describe the integration methods - [`test/`](../test/#mlos-github-tree-view) contains a directory and project to invoke each of the unit tests. - i.e. running `msbuild` or `make` in the `test/` directory will also run all of the tests. - [`scripts/`](../scripts/#mlos-github-tree-view) contains some helper scripts to initialize development environments, install tools, invoke build pipelines, run tests, etc. diff --git a/source/Examples/README.md b/source/Examples/README.md new file mode 100644 index 00000000000..04b510c083e --- /dev/null +++ b/source/Examples/README.md @@ -0,0 +1,4 @@ +# Examples + +- [SmartCache](./SmartCache/) +- [SmartSharedChannel](./SmartSharedChannel/) diff --git a/source/Examples/SmartCache/README.md b/source/Examples/SmartCache/README.md new file mode 100644 index 00000000000..6a7211ac804 --- /dev/null +++ b/source/Examples/SmartCache/README.md @@ -0,0 +1,138 @@ +# [SmartCache Example](./#mlos-github-tree-view) + +TODO: Some description of the example contained in this directory. + +This [`SmartCache`](./#mlos-github-tree-view) can be used to demonstrate a full end-to-end MLOS integrated microbenchmark for a "smart" component (in this case a cache). + +## Overview + +To do that, we run the (C++) `SmartCache` executable to communicate with the (C#) [`Mlos.Agent.Server`](../../Mlos.Agent.Server/#mlos-github-tree-view) over a shared memory channel provided by the [`Mlos.Core`](../../Mlos.Core/#mlos-github-tree-view) library. + +The `Mlos.Agent.Server` is essentially a small wrapper around several other communication channels to allow different components to connect for component experimentation convenience. + +It provides + +1. Shared memory communication channels via the [`Mlos.Agent`](../../Mlos.Agent/#mlos-github-tree-view) and [`Mlos.NetCore`](../../Mlos.NetCore/#mlos-github-tree-view) libraries. + +2. A [`Mlos.Agent.GrpcServer`](../../Mlos.Agent.GrpcClient/#mlos-github-tree-view) GRPC channel to allow driving the experimentation process from a Jupyter notebook. + +3. A GRPC client to connect to the (Python) [`mlos.Grpc.OptimizerMicroserviceServer`](../../Mlos.Python/mlos/Grpc/OptimizerMicroserviceServer.py#mlos-github-tree-view) to store and track those experiments. + +TODO: Diagrams + +## Building + +> Note: these commands are given relative to the root of the MLOS repo. +> +> To move there, you can execute the following within the repository: +> +> `cd $(git rev-parse --show-toplevel)` + +To build and run the necessary components for this example + +1. [Build the Docker image](../../../documentation/01-Prerequisites.md#build-the-docker-image) using the [`Dockerfile`](../../../Dockerfile#mlos-github-tree-view) at the root of the repository. + + ```shell + docker build --build-arg=UbuntuVersion=20.04 -t mlos/build:ubuntu-20.04 . + ``` + +2. [Run the Docker image](../../../documentation/02-Build.md#create-a-new-container-instance) you just built. + + ```shell + docker run -it -v $PWD:/src/MLOS --name mlos-build mlos/build:ubuntu-20.0 + ``` + +3. Inside the container, [build the compiled software](../../../documentation/02-Build.md#cli-make) with `make`: + + ```sh + make dotnet-build cmake-build + ``` + + > This will build everything using a default `CONFIGURATION=Release`. + > + > To just build `SmartCache` and `Mlos.Agent.Server`, execute the following: \ + > `make -C source/Examples/SmartCache && make -C source/Mlos.Agent.Server` + +4. For a `Release` build (the default), the relevant output will be at: + + - Mlos.Agent.Server: + + `out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll` + + - SmartCache: + + `out/cmake/Release/source/Examples/SmartCache/SmartCache` + + - SmartCache.SettingsRegistry: + + `out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU/SmartCache.SettingsRegistry.dll` + +## Executing + +The following commands will start the `Mlos.Server.Agent` and cause it to start the `SmartCache` component microbenchmark: + +```sh +export MLOS_SETTINGS_REGISTRY_PATH="out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU" + +tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll \ + out/cmake/Release/source/Examples/SmartCache/SmartCache +``` + +> Note: This is currently missing the `.json` file argument to connect to the optimizer service. + +```txt +Mlos.Agent.Server +Starting out/cmake/Release/source/Examples/SmartCache/SmartCache +observations: 0 +warn: Microsoft.AspNetCore.Server.Kestrel[0] + Unable to bind to http://localhost:5000 on the IPv6 loopback interface: 'Cannot assign requested address'. +info: Microsoft.Hosting.Lifetime[0] + Now listening on: http://localhost:5000 +info: Microsoft.Hosting.Lifetime[0] + Application started. Press Ctrl+C to shut down. +info: Microsoft.Hosting.Lifetime[0] + Hosting environment: Production +info: Microsoft.Hosting.Lifetime[0] + Content root path: /src/MLOS +Starting Mlos.Agent +Found settings registry assembly at out/dotnet/source/Examples/SmartCache/SmartCache.SettingsRegistry/obj/AnyCPU/SmartCache.SettingsRegistry.dll +observations: 1 +observations: 2 +observations: 3 +... +``` + +### Explanation + +The `Mlos.Agent` that gets started by the `Mlos.Agent.Server` waits for a signal that the component (`SmartCache`) has connected to the shared memory region before starting to poll the component for messages to process. +This is important in case the component is started independently. + +In this case, `Mlos.Agent.Server` itself starts the component. + +Once started, `SmartCache` will attempt to register its component specific set of shared memory messages with the `Mlos.Agent` in the `Mlos.Agent.Server` using `RegisterComponentConfig` and `RegisterAssemblyRequestMessage` from `Mlos.Core` and `Mlos.NetCore`. +That includes the name of the `SettingsRegistry` assembly (`.dll`) corresponding to that component's settings/messages. + +The `Mlos.Agent.Server` needs to be told where it can find those assemblies in order to load them so that it can process the messages sent by the component. +To do that, before we started the `Mlos.Agent.Server`, we first populated the `MLOS_SETTINGS_REGISTRY_PATH` environment variable with the directory path to the `SmartCache.SettingsRegistry.dll`. + +## Caveats + +- The system currently only supports one shared memory region and doesn't cleanup the shared memory after itself. + + As such, you may see hung processes when restarting after a failed experiment. + + To help with this, we currently provide a helper script to remove previous incarnations of the shared memory regions: + + ```sh + build/CMakeHelpers/RemoveMlosSharedMemories.sh + ``` + + You may also need to make sure that the processes using them are killed off. + For instance: + + ```sh + pkill SmartCache + pkill -f dotnet.*Mlos.Agent.Server.dll + ``` + + > Note: each of these commands should be executed inside the `Mlos.Agent.Server` execution environment (e.g. inside the docker container). diff --git a/source/Examples/SmartSharedChannel/README.md b/source/Examples/SmartSharedChannel/README.md new file mode 100644 index 00000000000..b7e3d1cd478 --- /dev/null +++ b/source/Examples/SmartSharedChannel/README.md @@ -0,0 +1,24 @@ +# [SmartSharedChannel Example](./#mlos-github-tree-view) + +This [SmartSharedChannel](./#mlos-github-tree-view) example demonstrates a using a microbenchmark of the MLOS shared memory channel to tune the MLOS shared memory channel itself. + +Here are some brief instructions on how to try it out: + +## Building + +1. Build the docker image +2. Create a docker image instance +3. Build the code: + + ```sh + make -C source/Mlos.Agent.Server + make -C source/Examples/SmartSharedChannel + ``` + +## Executing + +```sh +export MLOS_SETTINGS_REGISTRY_PATH=out/dotnet/source/Mlos.UnitTest/Mlos.UnitTest.SettingsRegistry/obj/AnyCPU:out/dotnet/source/Examples/SmartSharedChannel/SmartSharedChannel.SettingsRegistry/obj/AnyCPU + +./tools/bin/dotnet out/dotnet/source/Mlos.Agent.Server/obj/AnyCPU/Mlos.Agent.Server.dll out/cmake/Release/source/Examples/SmartSharedChannel/SmartSharedChannel +```