FICO Xpress OptimizationR

Last update February 2018

2.0
REFERENCE MANUAL

AEC2: Managing Amazon EC2 from Mosel

©2012–2019 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac
Corporation ("FICO"). Receipt or possession of this documentation does not convey rights to disclose,
reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation
purposes to determine whether to purchase a license to the software described in this documentation, oras otherwise set forth in a written software license agreement between you and FICO (or a FICO afﬁliate).
Use of this documentation and the software described in it must conform strictly to the foregoing
permitted uses, and no other use is permitted.
The information in this documentation is subject to change without notice. If you ﬁnd any problems in thisdocumentation, please report them to us in writing. Neither FICO nor its afﬁliates warrant that thisdocumentation is error-free, nor are there any other warranties with respect to the documentation except
as may be provided in the license agreement. FICO and its afﬁliates speciﬁcally disclaim any warranties,
express or implied, including, but not limited to, non-infringement, merchantability and ﬁtness for aparticular purpose. Portions of this documentation and the software described in it may contain copyrightof various authors and may be licensed under certain third-party licenses identiﬁed in the software,
documentation, or both.
In no event shall FICO or its afﬁliates be liable to any person for direct, indirect, special, incidental, or
consequential damages, including lost proﬁts, arising out of the use of this documentation or the software
described in it, even if FICO or its afﬁliates have been advised of the possibility of such damage. FICO and
its afﬁliates have no obligation to provide maintenance, support, updates, enhancements, or modiﬁcations
except as required to licensed users under a license agreement.
FICO is a registered trademark of Fair Isaac Corporation in the United States and may be a registeredtrademark of Fair Isaac Corporation in other countries. Other product and company names herein may be
trademarks of their respective owners.
AEC2
Deliverable Version: A
Last Revised: February 2018
Version 2.0

Contents
1

Introduction
1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Setup and creation of an Amazon Machine Image (AMI) for Mosel . . . . . . . . . . . . .

1
1
3

2 Main functions of the AEC2 package
2.1 Public declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Procedures and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getAllInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getConnString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getConnStringSSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getConnStringXSRV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getImages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
loadAEC2Conﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
runInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
terminateInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
updateInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
waitInstanceReady . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4
4
4
6
7
8
9
10
11
12
13
14
15

Appendix

16

A Contacting FICO
Product support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Product education . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Product documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sales and maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FICO Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About FICO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16
16
16
16
17
17
17
17

Index

18

Fair Isaac Corporation Conﬁdential and Proprietary InformationiCHAPTER 1

Introduction
Amazon Elastic Compute Cloud (EC2) is part of Amazon Web Services (AWS http://aws.amazon.com).
Using either a web interface or a set of API calls the service allows to run virtual machines on the
Amazon infrastructures. A virtual machine instance is started from an Amazon Machine Image (AMI):
this is the image of the machine to run (it includes both the operating system and a set of pre-installed
applications).
The AEC2 Mosel package is a subset of the AWS API for Mosel. It enables a model to:manage basic AWS functionality like creating keys, deﬁning security credentials, building AMIs, ...



start/stop and query the status of running virtual machines in the Cloud

start and use Mosel instances on virtual machines just like they were running on the local
network (using the standard mmjobs functionality)

This package is also available as an extension to XPRD (Java version) with which a Java program using
XPRD can manage instances created in EC2. This extension uses the same conﬁguration ﬁles as theMosel package.

1.1

Overview
The AEC2 package consists in a Mosel package (aec2.bim) and the program aec2setup.mos. In
addition to these components, system commands to connect to remote hosts using the SSH protocol
are also required. On Unix-like platforms, the programs ssh and scp are usually available; on Windows
systems, speciﬁc programs pcmdgen.exe, mpscp.exe and mplink.exe are included in the package
distribution.
Using Amazon EC2 requires the availability of machine images (AMI) in order to start virtual machines.
For the particular case of Mosel, the AMI must have Xpress installed and accept connections forrunning remote Mosel instances either via SSH or using the xprmsrv server: the provided setup program(aec2setup.mos) can be used to create appropriate images. This program, that is to be run once only,
also results in a set of conﬁguration ﬁles required to initialise the package when it is used by a model.
With the help of the mmjobs module a Mosel model can already start and manage remote instances forcreating distributed applications. The AEC2 package adds a set of routines to this framework for
managing EC2 virtual machines and generating the appropriate connection strings for the connect
function of mmjobs AEC2 is designed such that enabling an existing distributed model to use
resources in the Cloud merely requires the user to add a few statements to the original Mosel model
source code. For instance, consider the following model that compiles and then executes the model"mymodel.mos" on some remote host "myserver":Fair Isaac Corporation Conﬁdential and Proprietary Information

1

Introduction
model distuses 'mmjobs'
declarations
minst: Mosel
rmod: Model
end-declarations
if connect(minst, "myserver")<>0 thenexit(1)
end-ifif compile(minst, "", "rmt:mymodel.mos", "tmp:m.bim")<>0 thenexit(2)
end-ifload(minst, rmod, "tmp:m.bim")run(rmod)wait
dropnextevent
unload(rmod)
disconnect(minst)
end-model

The following example performs the same operations but using a virtual machine in EC2 instead of a
local server:model distec2
uses 'mmjobs','aec2'
declarations
ainst: EC2instanceminst: Mosel
rmod: Model
end-declarations
if not loadAEC2Config("aec2.acf") thenexit(-1)
end-if! load AEC2 configuration

ainst:=runInstance! start a virtual machine in the Cloud
if not waitInstanceReady(ainst, 300, true) thenexit(-2)
end-ifif connect(minst,getConnString(ainst))<>0 thenexit(1)
end-ifif compile(minst, "", "rmt:mymodel.mos", "tmp:m.bim")<>0 thenexit(2)
end-ifload(minst, rmod, "tmp:m.bim")run(rmod)wait
dropnextevent
unload(rmod)
disconnect(minst)
terminateInstance(ainst)
end-model! terminate the virtual machine

Note the use of function getConnString as input parameter for the mmjobs function connect: it
generates a valid connection string for the speciﬁed Amazon instance (either for an SSH or xprmsrv linkdepending on the default protocol).

Fair Isaac Corporation Conﬁdential and Proprietary Information2

Introduction

1.2

Setup and creation of an Amazon Machine Image (AMI) for Mosel
The AEC2 settings are stored in a set of conﬁguration ﬁles. The ’aec2setup.mos’ program will
conﬁgure your AWS account as needed and create these conﬁguration ﬁles. One of the tasks
performed by this program is to create a dedicate AMI running the Linux operating system. To this end,
an Xpress Linux package (either 32bit or 64bit depending on the needs) together with its associatedlicense ﬁle are required to run the model.
To run the setup program, copy into the same directory the Xpress Linux archive (ﬁle name in the form
"xp?.?.?_linux⁎_setup.tar"), the "xpauth.xpr" license and the "aec2setup.mos" program
itself then, from a command prompt type:mosel -s -c "exe aec2setup"

During the process, the program will ask various questions, in most cases a default answer is provided(noted in square brackets): simply hit enter if you do not know what to do. As part of the procedure avirtual machine is started in the Cloud and Xpress is installed on it in order to create the AMI to be usedlater on. Note that:

starting a virtual machine and creating the AMI may be quite long operations (up to several
minutes): do not interrupt the program during these operations
in case of failure, you can restart the program: it will recover information already setup.

Once the setup has completed, the following ﬁles have been created:"aec2.aid" the secret key-pair to access your AWS account. This ﬁle must be kept secret as it
gives full access to your AWS account"aec2.ask" the private key to log into virtual machines. The information stored in this ﬁlecannot be regenerated. If it is lost or corrupted, a new security credential will have to be created(i.e. delete the ﬁle and re-run aec2setup)"aec2.acf" the main conﬁguration ﬁle (that references the 2 others)

These 3 ﬁles are required by the AEC2 package when running a model using it.

Fair Isaac Corporation Conﬁdential and Proprietary Information

3

CHAPTER 2Main functions of the AEC2 package
2.1

Public declarations
An AMI is represented by the EC2image record type described as follows:
id:string
name:text
description:text! "Xpress for AEC2" for images created by aec2setup
location:text
snapshot:text
available:boolean
ispublic:booleanarchitecture:string
owner:string
ownerid:string

A running (or recently terminated) instance is represented by the EC2instance record type publishing
the following ﬁelds:
image:stringstate:integer! image name
! AEC2_PENDING/AEC2_RUNNING/AEC2_SHUTTING_DOWN/! AEC2_STOPPED/AEC2_STOPPING/AEC2_TERMINATED! public DNS name! key used for ssh connections! e.g. "t1.micro"

dns:text
key:text
type:string
launchtime:datetime
ipaddr:text! public IP

The package also publishes the following global variables:
aec2_image:string! image nameaec2_type:string! instance type (e.g. "t1.micro")
aec2_secgrp:string! security group for SSH sessions
aec2_connmode:string ! connecion mode: "xprmsrv" or "ssh"aec2_xsrvctx:string! xprmsrv context
aec2_xsrvpass:string ! xprmsrv password
aec2_xsrvport:integer ! xprmsrv connection port

These variables are initialised when loading the conﬁguration ﬁle using loadAEC2Config but may be
modiﬁed directly after this routine has been called.

2.2

Procedures and functions
getAllInstances

Retrieve a list of Instances from AWS.

Fair Isaac Corporation Conﬁdential and Proprietary Information

p. 6

4

Main functions of the AEC2 package

getConnString

Generate a connection string.

p. 7

getConnStringSSH

Generate a connection string for an SSH link.

p. 8

getConnStringXSRVGenerate a connection string for an xprmsrv server.

p. 9

getImages

Retrieve a list of AMI from AWS.

p. 10

loadAEC2Config

Load a conﬁguration ﬁle and initialise the package.

p. 11

runInstanceStart a new instance in EC2.

p. 12

terminateInstanceTerminate the speciﬁed instance.

p. 13

updateInstance

Update instance information.

p. 14

waitInstanceReady

Wait for an instance to be ready.

p. 15

Fair Isaac Corporation Conﬁdential and Proprietary Information

5

Main functions of the AEC2 package

getAllInstances
Purpose
Synopsis

Retrieve a list of Instances from AWS.
function getAllInstances:list of EC2instance

Return value
List of running (or recently terminated) instances.
Further information
The returned list may contain instances that have already terminated. It is important to check theactual state of an instance before using it (ﬁeld state of the EC2instance type).
Related topics
getImages.

Fair Isaac Corporation Conﬁdential and Proprietary Information

6

Main functions of the AEC2 package

getConnString
Purpose
Synopsis

Generate a connection string.
function getConnString(inst:EC2instance):stringArgument
inst

Target instance

Return value
A connection string suitable for the connect routine of mmjobs.
Further information
This function calls either getConnStringSSH or getConnStringXSRV depending on the value of thevariable aec2_connmode.
Related topics
getConnStringXSRV, getConnStringSSH.

Fair Isaac Corporation Conﬁdential and Proprietary Information

7

Main functions of the AEC2 package

getConnStringSSH
Purpose
Synopsis

Generate a connection string for an SSH link.
function getConnStringSSH(inst:EC2instance):stringArgument
inst

Target instance

Return value
A connection string suitable for the connect routine of mmjobs.
Further information
The resulting connection string is of the form "rcmd:mplink -batch -ssh -i keyfile
user@ipaddr mosel -r" on Windows systems and "rcmd:ssh -o
StrictHostKeyChecking=no -i keyfile user@ipaddr mosel -r" on Unix-like operating
systems.
Related topics
getConnStringXSRV, getConnString.

Fair Isaac Corporation Conﬁdential and Proprietary Information

8

Main functions of the AEC2 package

getConnStringXSRVPurpose
Synopsis

Generate a connection string for an xprmsrv server.
function getConnStringXSRV(inst:EC2instance):stringArgument
inst

Target instance

Return value
A connection string suitable for the connect routine of mmjobs.
Further information
The resulting connection string is of the form "xsrv:ipaddr(port)/ctx/pass".
Related topics
getConnStringSSH, getConnString.

Fair Isaac Corporation Conﬁdential and Proprietary Information

9

Main functions of the AEC2 package

getImages
Purpose
Synopsis

Retrieve a list of AMI from AWS.
function getImages(Id:string, name:string, desc:string):list of EC2image

Arguments
Id
name
desc

Image ID (or an empty string)
Image name (or an empty string)
Image description (or an empty string)

Return value
List of images with the speciﬁed properties.
ExampleThe following example retrieves all images created by aec2setup and the speciﬁcation of the default
image used to start new instances:xpimgs:=getImages("","","Xpress for AEC2⁎")
defimg:=getImages(aec2_image,"","")

Further information
1. Each of the parameters is used as a ﬁlter: the resulting list will keep only images with thecorresponding property matching the ﬁlter. Filters support wildcard charcaters "⁎" (any sequence ofcharacter possibly empty) and "?" (any character). An empty string is equivalent to "⁎" (any string).
2. Images created by the program aec2setup have the string "Xpress for AEC2" included in theirdescription: this can be used to ﬁnd existing images compatible with the package.
Related topics
getAllInstances.

Fair Isaac Corporation Conﬁdential and Proprietary Information

10

Main functions of the AEC2 package

loadAEC2Conﬁg
Purpose
Synopsis

Load a conﬁguration ﬁle and initialise the package.
function loadAEC2Config(confFile:string):boolean

Argument
confFile Conﬁguration ﬁle nameReturn value
true if operation succeeded.
Further information
This function must be called before any other routine of the package. The conﬁguration ﬁles are
created by running the "aec2setup.mos" program.

Fair Isaac Corporation Conﬁdential and Proprietary Information

11

Main functions of the AEC2 package

runInstancePurpose
SynopsisStart a new instance in EC2.
function runInstance:EC2instance

Return value
Instance record referencing the created instance.
Further information
This function starts a new instance using the current conﬁguration (in particular using ’aec2_image’ as
the image). Note that an instance needs some time before it is ready to execute commands — thisroutine does not wait for the instance to be ready: use waitInstanceReady for this purpose.
Related topics
waitInstanceReady, updateInstance.

Fair Isaac Corporation Conﬁdential and Proprietary Information

12

Main functions of the AEC2 package

terminateInstancePurpose
Synopsis

Terminate the speciﬁed instance.
procedure terminateInstance(inst:EC2instance)

Argument
inst

Instance to terminate

Related topics
runInstance.

Fair Isaac Corporation Conﬁdential and Proprietary Information

13

Main functions of the AEC2 package

updateInstancePurpose
Synopsis

Update instance information.
procedure updateInstance(inst:EC2instance)

Argument
inst

Instance object to update

Further information
An EC2instance object contains information on an instance running in EC2. This information is notnecessarily up to date: this procedure queries AWS and updates properties stored in the corresponding
record.

Fair Isaac Corporation Conﬁdential and Proprietary Information

14

Main functions of the AEC2 package

waitInstanceReady
Purpose
Synopsis

Wait for an instance to be ready.
function
waitInstanceReady(inst:EC2instance,delay:integer,verbose:boolean):boolean

Arguments
inst
Instance to wait fordelay
Maximum amount of time (seconds) to wait
verbose Display progress bar if true
Return value
true if the instance was ready before the expiration of the speciﬁed delay.
Further information
This function waits at most delay seconds for the instance inst to be ready. If verbose is true, adot will be displayed at regular intervals.
Related topics
runInstance, updateInstance.

Fair Isaac Corporation Conﬁdential and Proprietary Information

15

APPENDIX A

Contacting FICO
FICO provides clients with support and services for all our products. Refer to the following sections formore information.

Product support
FICO offers technical support and services ranging from self-help tools to direct assistance with a FICO
technical support engineer. Support is available to all clients who have purchased a FICO product andhave an active support or maintenance contract. You can ﬁnd support contact information and a link to
the Customer Self Service Portal (online support) on the Product Support home page(www.ﬁco.com/en/product-support).
The FICO Customer Self Service Portal is a secure web portal that is available 24 hours a day, 7 days aweek from the Product Support home page. The portal allows you to open, review, update, and close
cases, as well as ﬁnd solutions to common problems in the FICO Knowledge Base.
Please include ’Xpress’ in the subject line of your support queries.

Product education
FICO Product Education is the principal provider of product training for our clients and partners.
Product Education offers instructor-led classroom courses, web-based training, seminars, and training
tools for both new user enablement and ongoing performance support. For additional information, visit
the Product Education homepage at www.ﬁco.com/en/product-training or email
producteducation@ﬁco.com.

Product documentation
FICO continually looks for new ways to improve and enhance the value of the products and services weprovide. If you have comments or suggestions regarding how we can improve this documentation, let
us know by sending your suggestions to techpubs@ﬁco.com.
Please include your contact information (name, company, email address, and optionally, your phone
number) so we may reach you if we have questions.

Fair Isaac Corporation Conﬁdential and Proprietary Information

16

Contacting FICO

Sales and maintenanceIf you need information on other Xpress Optimization products, or you need to discuss maintenancecontracts or other sales-related items, contact FICO by:

Phone: +1 (408) 535-1500 or +44 207 940 8718



Web: http://www.ﬁco.com/optimization and use the available contact forms

Related services
Strategy Consulting: Included in your contract with FICO may be a speciﬁed amount of consulting time
to assist you in using FICO Optimization Modeler to meet your business needs. Additional consulting
time can be arranged by contract.
Conferences and Seminars: FICO offers conferences and seminars on our products and services. For
announcements concerning these events, go to www.ﬁco.com or contact your FICO accountrepresentative.

FICO Community
The FICO Community is a great resource to ﬁnd the experts and information you need to collaborate,
support your business, and solve common business challenges. You can get informal technicalsupport, build relationships with local and remote professionals, and improve your business practices.
For additional information, visit the FICO Community (community.ﬁco.com/welcome).

About FICO
FICO (NYSE:FICO) powers decisions that help people and businesses around the world prosper.
Founded in 1956 and based in Silicon Valley, the company is a pioneer in the use of predictive analytics
and data science to improve operational decisions. FICO holds more than 165 US and foreign patents
on technologies that increase proﬁtability, customer satisfaction, and growth for businesses inﬁnancial services, telecommunications, health care, retail, and many other industries. Using FICO
solutions, businesses in more than 100 countries do everything from protecting 2.6 billion payment
cards from fraud, to helping people get credit, to ensuring that millions of airplanes and rental cars arein the right place at the right time. Learn more at www.ﬁco.com.

Fair Isaac Corporation Conﬁdential and Proprietary Information

17

IndexG
getAllInstances, 6
getConnString, 7
getConnStringSSH, 8
getConnStringXSRV, 9
getImages, 10
L
loadAEC2Config, 11
R
runInstance, 12TterminateInstance, 13UupdateInstance, 14
W
waitInstanceReady, 15

Fair Isaac Corporation Conﬁdential and Proprietary Information

18