DOcrossrates – how to use IBM CPLEX on Bluemix
I recently created an online demo on Bluemix, DOcrossrates: http://docrossrates.eu-gb.mybluemix.net/
The demo shows how mathematical optimization (aka Decision Optimization) can be used in a cloud based web application. The demo implements online currency trading optimization, as a simple example for mathematical optimization. For more information on the demo itself and its business or functional background, please see: http://docrossrates.eu-gb.mybluemix.net/DOcrossrates.pdf
In the following, I describe how to implement the demo. Please note that for many parts of it there’s a variety of ways to do it. I am not saying that my way of doing it is the best. I am simply saying that this way is an easy way and it works.
The demo is based on the following IBM cloud services:
- IBM Bluemix: https://console.ng.bluemix.net/
- IBM Decision Optimization on Cloud – DOcloud: https://developer.ibm.com/docloud/
The first thing you have to do is to register with these services. At the time of writing, you can use the services for free for a certain period and under certain conditions, as stated there. This trial service is enough to build and run our demo. On both sites you will also find some nice getting started tutorials. You might want to check those out – but you don’t need to for the following. I will guide you through all necessary steps here.
When you register with DOcloud, you get access to the DOcloud API via two credentials: an access (or Base) URL, and a personal API key. We use both further down the road, when we put all the things together.
Your first Bluemix application
Once you’ve registered with Bluemix, you can create your first Bluemix application in your Bluemix home dashboard: https://console.eu-gb.bluemix.net/?direct=classic/#/resources
- Click CREATE APP
- Click WEB
- Click (.js) for the SDK for Node.js
- Give your app a name and click FINISH
The app is created for you on Bluemix: it is automatically deployed, started, and then is immediately online – you can access and use it now from anywhere in the internet!
Congratulations – you have created your first Bluemix application!
Our application consists of:
- app.js – the web server
- docloud.js – the connection to DOcloud
- crossrates.mod – the optimization model, written in the Optimization Programming Language (OPL)
- some data files in JSON format
- some packages that our app depends on, both on the server side (in the folder node_modules, including docloud-api), and on the client side (in the folder public)
Let’s take a quick look at app.js and docloud.js since they provide the core functionality of our web application. You will find all files necessary for the demo application in the ZIP file that I have attached to this blog entry.
This is the central piece of the whole application. It creates a web server and attaches and integrates all necessary services, like the DOcloud service. You’ll find the code of app.js in the attached ZIP file.
The table below gives a brief overview on what app.js does. This is just the usual web application stuff – but (in my opinion) in a very short and concise way, making use of the Node.js framework.
|1-10||Initialization of global data.|
|11-18||Loads external modules.|
|19-32||Sets some parameters in the web server.|
|42-46||Starts the web server.|
|47-53||Some string utility functions.|
|54-73||Service function dataList(): lists available data files on the server. Note that this function takes an HTTP request and a response as arguments.|
|74-83||Service function loadData(): loads a data set and passes it to the client. The client then displays the data set in the (Dojo dgrid, http://dgrid.io/) table named gridData (defined in index.ejs, see the attached ZIP).|
|84-end||Service function runOptim(): loads the data set (given by the client by its name), runs the optimization (via docloud.js) and returns the solution, to be displayed in the table named gridSol (see index.ejs).|
|1-5||Loads external modules (including the DOcloud Node.js client).|
|6-11||Creates a DOcloud client to communicate with the service. Note that here you’ll need to put the above mentioned credentials, service URL and key.|
|12-14||Deletes all old jobs, for our key, on the DOcloud server. Sometimes jobs might hang and then our job queue, which is limited to max 5 jobs (for the trial version of the service), fills up. We clear it here.|
|15-20||Error handling function.|
|21||Exports the following code as external function execute(). Note that the parameter cb provides a callback function, to be given by the caller (app.js); this function is called under different circumstances later on. To use callback functions like this is a very common pattern in Node.js.|
|23-end||Creates and executes the optimization job on the server:
Putting it all together
You have created your first Bluemix application, and we have all the code ready for our app using CPLEX on the cloud – aka DOcloud. So let’s put everything together:
- Go to the Bluemix console (https://console.ng.bluemix.net) and login:
- In the list of your applications, click the one that you’ve created above.
- Then, click the 2 “up” arrows left of “Overview” – a menu will appear.
- Click “Start Coding” – you will be asked “How do you want to start coding?”
- Click CF (for Cloud Foundry) Command Line Interface
- Follow the steps described there, BUT:
- After you have downloaded the starter code of your app, Don’t extract it into the new folder!
- Instead, extract the contents of the ZIP that you’ll find attached to this blog into that folder. It will give you app.js, docloud.js and the rest of the code in that folder.
- Open the starter code ZIP (that you’ve downloaded from Bluemix) and copy only the file manifest.yml out of it into your app folder.
- Edit docloud.js there and enter your(!) DOcloud credentials (lines 9&10; note that the first string is followed by a comma, after the quote, while the second is not):
url : ‘https://here-goes-the-api-url/…/…’,
clientId : ‘api_xxx-yyy-zzz’
- Then continue with the steps described in the Bluemix console – essentially pushing the new app code to Bluemix and restarting the online app.
- Finally, you’ll open the URL of your app in a browser, and you have our demo app running!
Isn’t this great? At least when it worked for me the first time, I felt like – wow…
Now you have the demo app up and running as your own Bluemix app. Note that you also have a local copy of it (in the folder you’ve created) that you can use for local development and even run locally – and which you can then deploy again to Bluemix with the commands that you’ve used above!
In order to run and test the app locally, you need to install Node.js, which is also not a big deal:
- Install Node.js: https://nodejs.org/en/download/
- Run the app: Open a command line window and CD to the directory that contains the app files that we worked on above. Then execute the following command:
- Now you can open the locally running web app in any browser: http://localhost:8899
NOTE that depending on the actual Node.js version you are using, you might encounter an error message complaining about a “problem with the zlib package”. In this case, simply remove the folder node_modules/docloud-api/node_modules/zlib.
In this post you’ve learned how to get started with Bluemix, create a simple web app and integrate it with CPLEX on the Cloud – not bad, eh?