AMPL Class
An AMPL translator. An object of this class can be used to do the following tasks:
Run AMPL code. See ampl.AMPL.Eval
.
Read models and data from files. See ampl.AMPL.read
and
ampl.AMPL.ReadData
.
Solve optimization problems constructed from model and data (see
ampl.AMPL.Solve
).
Access single elements of an optimization problem. See the generic
ampl.AMPL.GetEntity
and the generic ampl.AMPL.GetVariable
,
ampl.AMPL.GetObjective
, ampl.AMPL.GetConstraint
,
ampl.AMPL.GetSet
and ampl.AMPL.GetParameter
.
Access lists of available elements of an optimization problem. See
ampl.AMPL.GetVariables
, ampl.AMPL.GetObjectives
,
ampl.AMPL.GetConstraints
, ampl.AMPL.GetSets
and
ampl.AMPL.GetParameters
.
AMPL stores one or more problems which may consume substantial amount of
memory. An AMPL object without any references to it will eventually be freed
by the Java garbage collector and all the memory and other resources
associated with it will be released. This includes any resources which are
out of scope of the garbage collector such as open files or memory managed by
the native code. Call ampl.AMPL.Close
to release these resources
explicitly.
The initialization of the Java representation of the AMPL entities (any class
derived from ampl.Entities.Entity
) is lazy and consists of two steps. When a
function listing available elements is called, only a shallow list with
names, types and declarations of the elements is populated. The same happens
when a reference to a Java representation of one entity is obtained (through
a call to ampl.AMPL.GetEntity
or any other single entity factory
function). When accessing any instance of an entity (through the methods
'get' of any class), the (memory hungry) list of instances for that entity is
created.
Consistency is maintained automatically. Any command issued to the translator
through ampl.AMPL.Eval
and similar functions invalidates all entities,
and any further access to any entity will require communication between the
native translator and the Java code. Conversely, any operation called through
the Java equivalent function, like fixing variables or solving the model will
invalidate only the entities involved. A list of dependencies between
entities is automatically updated.
Error handling is two-faced:
1. Errors coming from the underlying AMPL translator (e.g. syntax errors and
warnings obtained calling the ampl.AMPL.Eval
method) are handled by
the event ampl.AMPL.Error
. Note that by default the event is
disabled. To enable it, call ampl.AMPL.EnableErrorAndWarningRouting
.
2. Generic errors coming from misusing the API, which are detected in .NET,
are thrown as exceptions.
The default implementation of the error handler throws exceptions on errors
and prints to console on warnings.
The output of every user interaction with the underlying translator is
handled by the event ampl.AMPL.Output
, which is called at each
block of output from the translator after the function ampl.AMPL.EnableOutputRouting
is called.
- Namespace
ampl
- Assemblies
-
[ComVisible(false)]
public class AMPL : IDisposable
-
class ampl.AMPL
-
AMPL()
Default constructor: creates a new AMPL instance with
the default environment.
-
AMPL(ampl.Environment)
Creates a new AMPL instance with the specified environment
public AMPL(Environment e)
-
Cd(System.String)
Change or display the current working directory (see
https://en.wikipedia.org/wiki/Working_directory ).
- Arguments
directoryName (System.String) – New working directory or null
(to display the working directory)
- Return type
System.String
public string Cd(string directoryName = null)
-
Close()
Stops the underlying engine and release its resources.
Any further attempt to execute optimisation commands
without restarting it will throw an exception.
-
Display(System.String[])
public void Display(params string[] args)
-
Dispose()
-
-
Dispose(System.Boolean)
protected virtual void Dispose(bool disposing)
-
EnableErrorAndWarningRouting()
Enable routing of AMPL error and warning handling via the C# wrapper.
Must be called to enable handling of errors and warning
through handlers registered with ampl.AMPL.Error
and ampl.AMPL.Warning
.
public void EnableErrorAndWarningRouting()
-
EnableOutputRouting()
Enable routing of AMPL console outputs through the C# wrapper.
Must be called to enable handling of the output through a personalised
handler registered with ampl.AMPL.Output
.
public void EnableOutputRouting()
-
Eval(System.String)
Parses AMPL code and evaluates it as a possibly empty sequence of AMPL
declarations and statements.
As a side effect, it invalidates all entities (as the passed statements
can contain any arbitrary command); the lists of entities will be
re-populated lazily (at first access)
The output of interpreting the statements is passed to the current
OutputHandler (see getOutputHandler and
setOutputHandler).
By default, errors are reported as exceptions and warnings are printed on
stdout. This behavior can be changed reassigning an
ErrorHandler using setErrorHandler.
- Arguments
AMPLStatements (System.String) – A collection of AMPL statements
and declarations to be passed to the interpreter
public void Eval(string AMPLStatements)
-
EvalAsync(System.String, System.Action)
Interpret asynchronously the given AMPL statements
- Arguments
cb (System.Action) – Call back to be executed when completed
public void EvalAsync(string AMPLStatements, Action cb)
-
Expand(ampl.Entities.Entity[])
public void Expand(params Entity[] entities)
-
ExportData(System.Boolean)
Get all the data currently loaded in dat format
- Arguments
includeSets (System.Boolean) – True to include set members in the export, false to exclude them
- Return type
System.String
public string ExportData(bool includeSets = true)
-
ExportData(System.String, System.Boolean)
Writes all the data currently loaded to file in dat format
- Arguments
fileName (System.String) – The file to write
includeSets (System.Boolean) – True to include set members in the export, false to exclude them
public void ExportData(string fileName, bool includeSets = true)
-
ExportModel()
Returns all the declarations in the current AMPL instance
- Return type
System.String
public string ExportModel()
-
ExportModel(System.String)
Writes the declarations in the current AMPL instance to file
- Arguments
fileName (System.String) – The file to write
public void ExportModel(string fileName)
-
GetBoolOption(System.String)
Get the current value of the specified boolean option.
- Arguments
name (System.String) – Option name
- Return type
System.Nullable<System.Boolean>
- Returns
The option value, null if the specified option
does not exist
public bool? GetBoolOption(string name)
-
GetConstraint(System.String)
Get the constraint with the corresponding name
- Arguments
name (System.String) – Name of the constraint to be found
- Return type
ampl.Entities.Constraint
public Constraint GetConstraint(string name)
-
GetConstraints()
Get the defined constraints
- Return type
ampl.Entities.ConstraintMap
public ConstraintMap GetConstraints()
-
GetData(System.String[])
<p>Get the data corresponding to the display statements. The statements can
be AMPL expressions, or entities. It captures the equivalent of the command:
</p>
<p>
<code>display ds1, …, dsn;</code>
</p>
<p> where<code> ds1, …, dsn </code>are the <code data-dev-comment-type=”paramref” class=”paramref”>statements</code> with which the function is called. </p>
<p>As only one DataFrame is returned, the operation will fail if the results
of the display statements cannot be indexed over the same set. As a result, any
attempt to get data from more than one set, or to get data for multiple
parameters with a different number of indexing sets will fail.</p>
- Arguments
statements (System.String<System.String>[]) – The display statements to be fetched
- Return type
ampl.DataFrame
- Returns
DataFrame capturing the output of the display command in tabular form
public DataFrame GetData(params string[] statements)
-
GetDblOption(System.String)
Get the current value of the specified option.
- Arguments
name (System.String) – Option name
- Return type
System.Nullable<System.Double>
- Returns
The option value, null if the specified option
does not exist
public double? GetDblOption(string name)
-
GetEntity(System.String)
Get entity corresponding to the specified name (looks for it in all types
of entities)
- Arguments
name (System.String) – Name of the entity
- Return type
ampl.Entities.Entity
- Returns
The AMPL entity with the specified name
public Entity GetEntity(string name)
-
GetIntOption(System.String)
Get the current value of the specified option.
- Arguments
name (System.String) – Option name
- Return type
System.Nullable<System.Int32>
- Returns
The option value, null if the specified option
does not exist
public int? GetIntOption(string name)
-
GetObjective(System.String)
Get the objective with the corresponding name
- Arguments
name (System.String) – Name of the objective to be found
- Return type
ampl.Entities.Objective
public Objective GetObjective(string name)
-
GetObjectives()
Get the defined objectives
- Return type
ampl.Entities.ObjectiveMap
public ObjectiveMap GetObjectives()
-
GetOption(System.String)
Get the current value of the specified option.
- Arguments
name (System.String) – Option name
- Return type
System.String
- Returns
The option value, null if the specified option
does not exist
public string GetOption(string name)
-
GetOutput(System.String)
Equivalent to ampl.AMPL.eval
but returns the output as a
string.
- Arguments
AMPLStatements (System.String) – A collection of AMPL statements
and declarations to be passed to the interpreter
- Return type
System.String
public string GetOutput(string AMPLStatements)
-
GetParameter(System.String)
Get the parameter with the corresponding name
- Arguments
name (System.String) – Name of the parameter to be found
- Return type
ampl.Entities.Parameter
public Parameter GetParameter(string name)
-
GetParameters()
Get the defined parameters
- Return type
ampl.Entities.ParameterMap
public ParameterMap GetParameters()
-
GetSet(System.String)
Get the set with the corresponding name
- Arguments
name (System.String) – Name of the set to be found
- Return type
ampl.Entities.Set
public Set GetSet(string name)
-
GetSets()
Get the defined sets
- Return type
ampl.Entities.SetMap
-
GetValue(System.String)
Get a scalar value from the underlying AMPL interpreter,
as a double or a string.
- Arguments
scalarExpression (System.String) – An AMPL expression which evaluates
to a scalar value.
- Return type
ampl.Variant
public Variant GetValue(string scalarExpression)
-
GetVariable(System.String)
Get the variable with the corresponding name
- Arguments
name (System.String) – Name of the variable to be found
- Return type
ampl.Entities.Variable
public Variable GetVariable(string name)
-
GetVariables()
Get the defined variables
- Return type
ampl.Entities.VariableMap
public VariableMap GetVariables()
-
Interrupt()
Interrupt an underlying asynchronous operation (execution of AMPL code by the
AMPL interpreter). An asynchronous operation can be started via evalAsync(), solveAsync(), readAsync() and
readDataAsync().
Does nothing if the engine and the solver are idle.
-
Read(System.String)
Interprets the specified file (script or model or mixed) As a side effect,
it invalidates all entities (as the passed file can contain any arbitrary
command); the lists of entities will be re-populated lazily (at first
access)
- Arguments
filename (System.String) – Path to the file (Relative to the
current working directory or absolute)
public void Read(string filename)
-
ReadAsync(System.String, System.Action)
Interprets the specified file asynchronously, interpreting it as a model
or a script file. As a side effect, it invalidates all entities (as the
passed file can contain any arbitrary command); the lists of entities
will be re-populated lazily (at first access)
- Arguments
-
public void ReadAsync(string filename, Action cb)
-
ReadData(System.String)
Interprets the specified data file. As a side effect,
it invalidates all entities (as the passed file can contain any arbitrary
command); the lists of entities will be re-populated lazily (at first
access)
- Arguments
filename (System.String) – Path to the file (Relative to the
current working directory or absolute)
public void ReadData(string filename)
-
ReadDataAsync(System.String, System.Action)
Interprets the specified data file asynchronously, interpreting it as a model
or a script file. The file is interpreted as data.
As a side effect, it invalidates all entities (as the file can contain
arbitrary commands); the lists of entities will be re-populated
lazily (at first access)
- Arguments
-
public void ReadDataAsync(string filename, Action cb)
-
ReadTable(System.String)
Read the table corresponding to the specified name, equivalent to the
AMPL statement:
read table tableName;
- Arguments
tableName (System.String) – Name of the table to be read
public void ReadTable(string tableName)
-
Reset()
Clears all entities in the underlying AMPL interpreter,
clears all maps and invalidates all entities
-
SetData(ampl.DataFrame, System.String)
Assign the data in the dataframe to the AMPL entities with the names
corresponding to the column names.If setName is null, only the
parameters value will be assigned.
- Arguments
-
public void SetData(DataFrame df, string setName = null)
-
SetOption(System.String, System.Boolean)
Set an AMPL option to a specified boolean value.
In AMPL, boolean options are represented as integer:
0 for false, 1 for true.
- Arguments
-
public void SetOption(string name, bool value)
-
SetOption(System.String, System.Double)
Set an AMPL option to a specified double value.
- Arguments
-
public void SetOption(string name, double value)
-
SetOption(System.String, System.Int32)
Set an AMPL option to a specified integer value.
- Arguments
-
public void SetOption(string name, int value)
-
SetOption(System.String, System.String)
Set an AMPL option to a specified value.
- Arguments
-
public void SetOption(string name, string value)
-
Show(ampl.Entities.Entity[])
public void Show(params Entity[] entities)
-
Solve()
Solve the current model
-
SolveAsync(System.Action)
Solve the current model asynchronously
- Arguments
cb (System.Action) – Call back to be executed when completed
public void SolveAsync(Action cb)
-
ToString()
Get a string describing the object. Returns the version of the API and
either the version of the interpreter or the message "AMPL is not
running" if the interpreter is not running (e.g. due to unexpected
internal error or to a call AMPL.Close())
- Return type
System.String
public override string ToString()
-
ampl.AMPL.CurrentObjectiveName
Get the name of the currently active objective
(see the objective
command), or null if no objective
has been declared or selected
- Return type
System.String
public string CurrentObjectiveName { get; }
-
Error()
Raised for each AMPL error, if ampl.AMPL.EnableErrorAndWarningRouting
has been called on the current object instance
- Return type
System.Action<AMPLException>
public event Action<AMPLException> Error
-
Output()
Raised for each AMPL output, if ampl.AMPL.EnableOutputRouting
has been called on the current object instance
- Return type
System.Action<Kind>
public event Action<Kind, string> Output
-
Warning()
Raised for each AMPL warning, if ampl.AMPL.EnableErrorAndWarningRouting
has been called on the current object instance
- Return type
System.Action<AMPLException>
public event Action<AMPLException> Warning