Linking a Modeling Language to MProbe

 Introduction

MProbe needs only a modest amount of data to link with a modeling language. This is primarily information about the elements of the model (variables, constraints, objectives) such as their names, types, etc., and a way to evaluate the functions at a given point. The requirements will be extremely similar to the information that you are already providing to solvers that are linked to your modeling language.

There are two ways for MProbe and the modeling language to communicate: (i) via standard subroutine DLL calls, or (ii) via queries of object properties and methods. With proper setup, either of these methods should be fine.

 Linking to AMPL

MProbe currently links to AMPL, so the linkage arrangement used for AMPL is informative. It works like this:

1. AMPL is invoked and used to create or recall or model. Commands given to AMPL tell it to write out files containing a representation of the model.
2. MProbe makes calls to a subroutine library to interact with the files in order to extract information about the model, or to evaluate functions at a point. The AMPL developers provide this subroutine library.

 It is not necessary for other language linkages to work in the same manner, as long as the necessary information, defined below, can be provided to MProbe.

Some Assumptions

Some assumptions convenient for the purposes of this document:

• Your modeling language is called "ABC" (the modeling language name is used as part of the relevant subroutine names below).
• "Function type" is 0 for objectives, and 1 for constraints.
• Lists (e.g. of variables, constraints, objectives), begin indexing at 0.
• All subroutines return an error code of some form if there is a problem, and exit gracefully. If possible, the routines can arrange for a graphical display of the exact wording of any error messages (via a Message Box for example).

Note that the interactions listed below, shown as subroutine calls for simplicity, avoid passing arrays as much as possible. This is because array passing seems to cause the most difficult inter-language calling problems. In fact it is possible to eliminate the need to pass the vectors of variables appearing in the constraints and objectives by instead passing a list of tuples (perhaps via a written file) of the form (obj/con flag, obj/con number, variable number) to indicate which variables appear in each objective or constraint.

MProbe is written in Visual Basic, and most modeling languages are written in some other language (C is popular). There is information about inter-language calling protocols in the Visual Basic documentation, and probably in the documentation for other languages as well.

Information and Data Needed by MProbe

What follows is an approximately chronological list of the interactions that the modeling language will have with MProbe, and of the information that the modeling language needs to provide to MProbe.

1. If interacting via an AMPL-style subroutine interface operating on files, MProbe needs to be able to tell the modeling language to write out the files describing the model. This may be via an operating system call, a prepared script file, or an object method. If interacting via objects, MProbe needs only to know where to find the model object.

2. MProbe calls a statistics function. This will only be called once, right at the start, so you can use it to construct any internal data structures you need etc. You may need to set your compiler switches so that the data structures stay alive after the function call completes, but MProbe is still running. Call this function ABC_Stats.

inputs (from MProbe):

• none (unless the filename is needed)

outputs (to MProbe):

Any stats you want to give. As an example, here is the list of statistics that I get from AMPL:

• number of variables (mandatory)
• number of binary variables
• number of other long variables
• number of constraints (mandatory)
• number of objectives (mandatory)
• number of nonlinear objectives
• number of ranged constraints
• number of nonlinear general constraints
• number of nonlinear network constraints
• number of variables appearing nonlinearly in both obj and constraints
• number of long variables appearing nonlinearly in both obj and const
• number of variables appearing nonlinearly in constraints
• number of variables appearing nonlinearly just in constriants
• number of variables appearing nonlinearly in objectives
• number of long variables appearing nonlinearly just in objectives
• number of linear network constraints
• number of nonzeros appearing in the jacobian matrix
• number of nonzeros in objectives

Note that AMPL writes the list of lists of variables and constraints in a prespecified order, so MProbe can e.g. determine a variable's type just by knowing it's place in the list. MProbe will need to know the variable and function types, but if the modeling language doesn't work with a prespecified ordering, this information can be provided later when MProbe requests specific variable and function data.

3. MProbe calls a function to fill in information about variables. It's easiest if MProbe calls the function once for each variable, but it can work with something that returns an array or data structure. Call this function ABC_VarData.

inputs:

• variable number

outputs:

• variable name
• variable type
• lower bound
• upper bound
• number of functions it appears in (provide this only if easy. MProbe can deduce it from information requested below)

4. MProbe calls a function to determine the number of variables that appear in a function. This lets it set up the appropriate arrays. Call this function ABC_NVars.

inputs:

• function number
• function type (obj or constr, i.e. 0 or 1)

outputs:

• number of variables in the function

5. MProbe will call a function to fill in information about constraints. Call this function ABC_ConData.

inputs:

• constraint number

outputs:

• name
• bound type (lower-only, upper-only, equality, range) [MProbe can deduce this from the RHS bounds]
• RHS lower bound
• RHS upper bound
• vector of variable indices of variables in the function
• algebraic shape (e.g. linear, quadratic, general nonlinear, etc.)

6. MProbe will call a function to fill in information about objectives. Call this function ABC_ObjData.

inputs:

• objective number

outputs:

• name
• objective direction (max or min)
• vector of variable indices of variables in the function
• algebraic shape (e.g. linear, quadratic, general nonlinear, etc.)

7. MProbe will repeatedly ask for the LHS values of various functions. This routine is called very frequently. Call this function ABC_FuncVal.

inputs:

• function type (obj or constraint, i.e. 0 or 1)
• function number
• array of variable values (can be ALL variables, or just the variables that appear in the function)

outputs:

• value of constraint LHS

8. MProbe will repeatedly ask for the gradient of various functions. This routine is called very frequently. Call this function ABC_Gradient.

inputs:

• function type (obj or constraint, i.e. 0 or 1)
• function number
• array of variable values (can be ALL variables, or just the variables that appear in the function)

outputs:

• function gradient at the input point

9. MProbe will need a cleanup routine if the user will be looking at a different model during the same session. There are no inputs or outputs. The library just needs to kill off any data structures that are being kept alive. Call this function ABC_CleanUp.

Back to MProbe home page.

Last update:October 12, 1999.