= EMSO Language Changes (version 0.9.52 and above) =

== '''ext''' keyword replaced by '''outer''' ==

The '''ext''' keyword was used to obtain a ''global'' parameter, it was replaced by '''outer'''.
I've observed that this keyword was not well suited for its meaning.

The idea from http://www.modelica.org is to have '''outer''' parameters, which means a parameter from one of the ''parents''.
Then the simulator will look for the parameter in the '''parent tree''' until it finds it (maybe it is found only on the FlowSheet but it can be matched before).

Usage example:
{{{
#!mso
Model stream
	PARAMETERS
	outer NComp as Integer(Brief = "Number of chemical components", Lower = 1); 

	VARIABLES
	F as flow_mol;
	T as temperature;
	P as pressure;
	z(NComp) as fraction (Brief = "Overall Molar Fraction");
	h as enth_mol (Brief = "Overall Molar Enthalpy");
	v as fraction (Brief = "Vapourisation fraction");
end

Model SubProcess
	PARAMETERS
	NComp as Integer(Brief = "Number of chemical components", Lower = 1);

	VARIABLES
	FL101 as flash; # flash model here uses the stream model
	FL102 as flash;
end

FlowSheet Flow
	DEVICES
	SUB01 as SubProcess;
	SUB02 as SubProcess;

	SET
	SUB01.NComp = 10;
	SUB02.NComp = 3;
end
}}}

Then when '''stream'''s are instantiated on the FlowSheet '''NComp''' will be a reference for '''NComp''' on the SubProcess.
Then we can have parameters which are ''global'' inside of a given ''context''.
If there is no '''intermediate''' declaration of the '''outer''' parameter, then it will be matched only on the '''FlowSheet''' and will works exactly
as the '''ext''' used to.

In the above example streams from '''SUB01''' '''cannot''' be connected with streams of '''SUB02'''.

Another example:
 * You have a model for a tray of a distillation column, and need a parameter to be the same for all trays
 * Then you declare such a parameter as '''outer''' on the tray model
 * And declare the parameter on the distillation column (each '''outer''' tray parameter will point to the distillation column one)
 * With the old '''ext''' implementation this is also possible, but the ''source'' parameter needs to be on the FlowSheet. In this case what about if you need two distillation columns on the same FlowSheet!?

== CalcObject's are now Plugin's ==

This is another example of keyword which is not directly understood by the users.
Then we adopted '''Plugin''' instead of '''CalcObject'''.

Usage:
{{{
#!mso
Model stream_therm as stream
	PARAMETERS
	outer  PP   as Plugin(Brief = "External Physical Properties", Type="PP");
	
	EQUATIONS
	h = (1-v)*PP.LiquidEnthalpy(T, P, z) + v*PP.VapourEnthalpy(T, P, z);
end
}}}

Another old problem with the Plugin's is that each Plugin '''call''' (e.g. '''PP.LiquidEnthalpy(T, P, z)''') generates a units of measurement warning.
In order to solve this problem, we created '''Type''' attribute.
This attribute can be set even for '''outer''' Plugins (as exemplified above).
Then we a new property set window was added, using this new dialog the user can register a DLL for each '''Type''' of Plugin.
This way the simulator can check the units of measurement and number of arguments when checking the model and not only when the simulation is run.
Besides this, the Plugin can be changed any time using the GUI without need to change the models.

The screenshot for the plugins configuration follows:

[[Image(PluginsConfiguration.png)]]

=== Plugin Declaration on FlowSheet ===

The declaration of a Plugin on a FlowSheet also changed:
{{{
#!mso
FlowSheet stream_test
	PARAMETERS
	PP as Plugin(Brief="Physical Properties",
		Type="PP",
		Components = ["1,3-butadiene", "isobutene", "n-pentane", "1-pentene", "1-hexene", "benzene"],
		LiquidModel = "PR",
		VapourModel = "PR"
	);
	NComp as Integer;

	SET
	NComp = PP.NumberOfComponents;
}}}

== Model Attributes ==

In previous versions only '''types''' had attributes, examples:
{{{
#!mso
positive as Real (Brief = "Positive General Constant", Default=1.0, Lower=-1e-6);
negative as Real (Brief = "Negative General Constant", Default=-1.0, Upper=0.0);
fraction as positive (Brief = "Fraction" , Default=0.5, Upper=1.00001);
}}}

In the above type declarations, '''Brief''', '''Lower''', etc are attributes.
Now we also have attributes for '''Model'''s, they are set using a new section called '''ATTRIBUTES''':

{{{
#!mso
Model MyTankModel
    ATTRIBUTES
    Icon="Tank";
    IconSize="normal";
    Brief="Model for a special kind of tank";
    Info="The model documentation. This should be more detailed than Brief,
    possibly spanning in multiple lines.
    It also should be good a have some wiki formating support in the documentation.
    Then we can have the library of models documentation automatically built based on it.";

    PARAMETERS
    ...
    VARIABLES
    ...
end
}}}

== Switcher for equations ==

In previous versions, continuous-discrete modeling is supported in EMSO only using the '''if''' statement.
But some more complex situations cannot be modeled with just a '''if'''.

For example, a safety valve which opens if the pressure is higher than 2 atm but closes only when the pressure is lower than the outside pressure.
This situation cannot be modeled by a trivial '''if'''. For this case, a State Transition Network (STN) is needed.

For this case the '''Switcher''' parameter type was added, usage:
{{{
#!mso
Model SafetyValve
    PARAMETERS
    ValveMode as Switcher(Valid = ["closed", "opened"], Default = "closed")
    ...
    EQUATIONS
    switch ValveMode
    case "closed":
       flow = 0 * "mol/h";
       when P > 2*"atm" switchto "opened";
    case "opened":
       flow = k*sqrt(P - Pout);
       when P < Pout*1.1 switchto "closed";
    end
    ...
end
}}}

In the piece of code above, there are the following news:
 * A new basic type called '''Switcher'''
 * The '''Switcher''' type has an extra attribute called '''Valid''' which are the valid values for the switcher
 * There is a '''switch''' command which can be used in the EQUATIONS
 * There is a '''when''' ... '''switchto''' command which can be used inside a '''case''' of a '''switch'''. NOTE: the '''when''' command is optional, however if this command is missing then the '''case''' is a '''black hole''': there is no way to get out! :)

== Units Of Measurement (UOM) ==

In previous versions of EMSO, there was Units Of Measurement (UOM) support for variables, parameters, equations, etc.
The problem is that the units of measurement are declared exactly as string text (with double quotes, eg "kg/h")

In recent versions we decided to distinguish texts from UOM using a different notation:
 * Units of measurement are declared with single quote, eg. 'kg/h'
 * Text elements are declared with double quote, eg. "This is a Text"

== Another UOM problems ==

In previous versions of EMSO, there was Units Of Measurement (UOM) support for variables, parameters, equations, etc.
But there was a potential problem when deriving types with a UOM:

{{{
#!mso
Model MyModel
    VARIABLES
    P as pressure(Unit = 'm')
    ...
end
}}}

The above model has serious problems:
 - '''P''' derived from a pressure type but has a ''length'' unit
 - What about the limits if the UOM changed?

In order to fix this kind of problem the following changes were implemented:
 - added a '''final''' modifier for the attributes, preventing it to be changed when deriving from it
 - added another attribute called '''DisplayUnit''', which should be compatible with '''Unit''' (the GUI will report all results converted to the '''DisplayUnit''')
 - now the limits are considered to be in respect to the '''Unit''' and not '''DisplayUnit'''
 - now all UOM declared in '''types.mso''' has the '''final''' attribute set

Sample code showing the news for UOM:
{{{
#!mso
# Pressure
pressure as Real (Brief = "Pressure", Default=1, Lower=1e-30, Upper=5e7, final Unit = 'atm');
press_delta as pressure (Brief = "Pressure Difference", Default=0.01, Lower=-5e6);
head as Real (Brief = "Head", Default=50, Lower=-1e6, Upper=1e6, final Unit = 'kJ/kg');

Model reactor
  VARIABLES
  P1 as pressure(Brief="Concentration", Unit='atm');
  # the above line will generate an error because pressure.Unit was declared as final
  P2 as pressure(Brief="Inlet concentration", DisplayUnit='m');
  # the above line will generate an error because a incompatible DisplayUnit was given
  P3 as pressure(Brief="Inlet concentration", DisplayUnit='atm'); # this one is correct
  ...
end
}}}

== OPTIONS section ==

Previous versions of EMSO support only a few common options for the solvers, such as '''relativeAccuracy''' and '''absoluteAccuracy'''. However, each solver has its own specific design options.

Now besides common options, there are solver specific options declared as follows:

{{{
#!mso
FlowSheet Myflowsheet
    ...
    OPTIONS
     time = [0:0.1:30];
     SparseAlgebra = true;

     NLASolver(File = "sundials",
               RelativeAccuracy = 1e-5,
               MaxIterations = 20
     );
     DAESolver(File = "dasslc",
               MaxOrder = 5,
               MaxLen = 400
     );
end
}}}

This way the user can supply '''any''' option to the solver.
EMSO will not check if the options are really supported by the solver at the time of reading the file.
The options will be checked only when the solver DLL is loaded (when actually trying to solve the problem).

The set of options which all '''NLASolver''' implementations should support:
||Option || Type || Description ||
||RelativeAccuracy || real || the desired relative accuracy of the solution, default '''1e-3''' ||
||AbsoluteAccuracy || real || the lowest value to be considered relevant when solving the problem, default '''1e-6''' ||
||MaxIterations || int || the maximum number of iterations, default '''100''' ||

The set of options which all '''DAESolver''' implementations should support:
||Option || Type || Description ||
||EventAccuracy || real || the accuracy in time when detecting state events (actually handled by EMSO, solver developers should not worry about this), default '''1e-2''' ||
||RelativeAccuracy || real || the desired relative accuracy of the solution, default '''1e-3''' ||
||AbsoluteAccuracy || real || the lowest value to be considered relevant when solving the problem, default '''1e-6''' ||

= Not Yet Implemented Suggestions =

Other suggestion for the '''OPTIONS''' section is to tell the simulator to use the steady-state solution as initial condition for the dynamic simulation. In this case the NLP for the initialization is not necessary, because all derivatives are set to zero. A suggestion to set this option could be using the '''InitialFile''':

{{{
#!mso
FlowSheet Myflowsheet
    ...
    OPTIONS
     Dynamic = true;
     TimeEnd = 30;
     RelativeAccuracy = 1e-8;
     AbsoluteAccuracy = 1e-9;
     InitialFile = "steady"; # or InitialFile = steady, without quotes
end
}}}

||Who || Opinion || Why ||
||Arge || '''agreed''' || proposed the change ||
||Rodolfo || '''agreed''' || will solve my problem with the gasifier that is not initializing, but the steady-state is working fine ||