See also: OATC Wiki Home

Date: September 7 - 10, 2009
Venue:BAW, Hamburg, Germany

Participants:

Standa Vanecek, DHI (s.vanecek@dhi.cz)
Daniele Andreis,Universita` di Trento,(daniele.andreis@gmail.com)
Roger Moore, on Mo + Tu (rvm@ceh.ac.uk)
Imran Younas on Mo + Tu (imun@ceh.ac.uk)
Stephen Morris on Mo + Tu (smorris@butford.co.uk)
Adrian Harper, Wallingford Software (adrian.harper@wallingfordsoftware.com)
Stef Hummel, Deltares (stef.hummel@deltares.nl)
~don, Deltares (gennadii.donchyts@deltares.nl) Mo - Wed
Peter Schade, Bundesanstalt fuer Wasserbau (peter.schade@baw.de)
~jgr@dhigroup.com, DHI (jgr@dhigroup.com)
Jan Gregersen, LicTek on Mo (afternoon) + Tu (Gregersen@LicTek.dk)

Apologies:
~jnh@dhigroup.com, DHI (jnh@dhigroup.com)
Rob Knapen, Alterra, Wageningen UR (Rob.Knapen@wur.nl)
~onnoroos, Alterra (Onno.Roosenschoon@wur.nl)
~moovida, Andrea Antonello, Universita` di Trento, (andrea.antonello@gmail.com)

Documents:

http://www.openmi.org/
http://sourceforge.net/projects/openmi
wiki.openmi.org

Table of contents

1. Minutes from previous OATC meeting

2. Documentation (most important)

Primary about C# based on this prepare Java

2.1 Standard

Automatic using Enterprise Architect

Modified 1.4 documentation

Changes in standard from 1.4

2.2 Model migration

From 1.4

For the new model (modified existing documentation)

Changes compare to previous version

2.3 SDK

Components migrated to the 2.0

Automatic generated EA

Changes 1.4

2.4 Tools

Modified 1.4 documentation

2.5 GUI

Progress as of 26/08/09

• Simple C# River example
  • Has been largley rewritten to conform with version 2
  • Uses base classes that hide some of drudgery of implementation, see (in namespace Oatc.OpenMI.Examples.ModelComponents.SimpleCSharpRiver.Wrapper)
    • class ItemBase {}
    • class OutputItemBase : ItemBase {}
    • class OutputItemDoubleBase: OutputItemBase{}
    • class InputItemBase : ItemBase {}
    • class InputItemDoubleBase : InputItemBase {}
    • class InputFlowItem : InputItemDoubleBase {}
    • class OutputFlowItem : OutputItemDoubleBase {}
    • class LinkableComponent  : ILinkableComponent, IDisposable {}
    • class RiverModelLinkableComponent : LinkableComponent {}
  • These have many TODO's which indicate Standard queries and unimplemented features.
• UI Editor
  • Largly Rewritten, still much to do, currently ....
    • Add/Remove Models
    • Composition Save, Open & Reload
    • New opr format valid for
      • models
      • exchange items (including decorators) examples under ??\Examples\ModelComponents\SimpleCSharpRiver\Data\Rivers
    • New Link dialog
      • Allows adding of decorators via factories (3rd party factories still to do)
    • New run dialog
      • Run, Abort & Reload
      • Real time update of model status via events
      • Basic Log info
    • Unit Tests
      • Completed
        • Stand alone Simple C# river
        • Two Simple C# rivers in series (Unidirectional)
      • Todo
        • Two Simple C# rivers in series (Unidirectional) with 1 decorator
        • Two Simple C# rivers in series (Unidirectional) with 2 decorators
        • Two Simple C# rivers in series (Bidirectional)

allow missing xmlns?

Conclusion: Give warning on missing xmlns field, but still load file.

Should be merged together!

IIdentifier
{
  /// Unique with respect to instantiated class type i.e.
  /// String unique = instantiated.Getype() + instantiated.UniqueId;
  /// UI's will use these for persistance, hence new component
  /// releases should maintain UniqueId value backwards compatability
  string UniqueId { get; }

  /// Short description.
  /// Suitable for displaying via a UI.
  /// Suitable for translation (hence set)
  /// NOTE: If passed back into component, might be changed, use UniqueId
  string Caption { get; set; }

  /// Longer, more generic, description.
  /// Suitable for displaying via a UI as additional info.
  /// Suitable for translation (hence set)
  /// NOTE: If passed back into component, might be changed, use UniqueId
  string Description { get; set }
}

Conclusion: Accepted. Name will be changed to IDescriptiveIdentifier.

IArgument
{
  ....
  
  /// Used by UI to determine whether user has to
  /// change/set the value
  /// Returned reasons can be displayed by UI in ignorance
  /// If true returned, reasons will be treated as warnings
  /// if false returned, resaons will be treated as a mixture of errors and warnings,
  /// the Caption should make clear whether a Error or a Warning. UI will display
  /// in order, so typically errors first warnings lator etc.
  bool IsValid(out IDescribable[] reasons); 
  
  ///
  /// *Must* the argument be provided or not?
  ///
  bool IsOptional { get; }
  
  /// == null: not applicable
  /// != null: list of possible values (of value type)
  IList<object> GetPossibleValues(); 
  
  /// Value only returns null if DefaultValue == null, as will 
  /// return DefaultValue anyway
   object Value { get; set; }

  /// Allows UI to persist values (e.g. too/from opr file)
  /// without knowing anything about their type
  string ValueAsString { get; set; }
 
}

Conclusions:
We agree that that we need a method access the value as an argument with a string. (Pictured above as ValueAsString. Gena will check other standards on the naming of this property or method.
We agree that the opr file will store the Assembly.Class info for a model instance, as well as the arguments that are used for that instance
Initialize call will let the component try to initialize itself. If the component does not succeed to initialize, it sets it state to Failed and throws an exception. The exception text will contain a clear message indicating what went wrong.
characteristics should be placed in Description. Together with IArgument.ValueType this provides enough information to know what type of arguments should be provided.
The Initialization of the Linkable Component will be split in first setting the arguments, and then initializing the model, see below. Please not that each argument key can appear in the list only once:

  ILinkableComponent.Arguments[0].ValueAsString = "value for argument 0";
  ILinkableComponent.Arguments[1].ValueAsString = "value for argument 1":
  ILinkableComponent.Arguments[2].ValueAsString = "value for argument 2":
  ILinkableComponent.Initialize();

class ExchangeItemEventArgs
{
   IExchangeItem _exchangeItem;

   /// Message describing the event
   String Message { set; get; };
}

/// Can targetItem be null, I think it can and we should ask programmers to allow for this
/// Null in case of stringing decorators together, and until full stack is
/// constructed targetItem might not be valid. 
/// Hence, implementer can use targetItem as a guide only, maybe rename to possibleTargetItem
IIdentifiable[] GetAvailableOutputDecorators(IOutputItem decoratedItem, IInputItem targetItem);

/// Redundant?
/// Note: Combined IDescribable/IIdentifiable makes working with factories much simpler
IDescribable GetDecoratorDescription(IIdentifiable decoratorId);

/// Dont need IExchangeItemDecoratorFactory to derive from IIdentifier/IDescribable
/// as we will either have the instance or Assembly/Type info to identify it
// However, do want
static public IDescribable IExchangeItemDecoratorFactory.Describes { get; }
// So without going to the cost of creating an instance can gather
// UI information for users to choose factories

/// why not?
IExchangeItemDecoratorFactory[] ILinkableComponent.Factories { get; }

/// REDUNANT: Deriving from IIdentifiable
/// as assembly/type info provides uniqueness
ILinkableComponent : IDescribable, IIdentifiable
/// prefer
static public IDescribable ILinkableComponent.Describes { get; }
/// Which gives UI usful display information without the cost
/// of instantiation of ILinkableComponent. This is then clearly
/// Linkable component information and not model related (which
/// might only be relevant after Initialise(...) has been called

/// CHANGE?
string[] ILinkableComponent.Validate();
/// to
IDescribable[] ILinkableComponent.Validate();

/// NEEDED .... or see Stefs suggestion
/// 1 requirement is needed for temporal components to allow progress % calculations
ITime ILinkableComponent.TimeHorizon

			/* Exception Responsabilities
			 * Any ILinkableComponent method can throw an exception of any type
			 * Before final throw out of a ILinkableComponent method
			 *  o Change Status to Failed
			 *  o Notify any delegates of Status change
			 *  o Throw
			 *  o Does NOT call Finish, thats for the calling code as Finish
			 *    as could in turn throw an exception!
			 */

/// Name change
/// Really means unadulterated cached values 
/// RawValues ?
IList IOutputItem.Values { get; }

/// NEW
bool IExchangeItem.ValidTimeSet(ITimeSet iTimeSet, out IDescribable[] reasons)
bool IExchangeItem.ValidValue(IList values, out IDescribable[] reasons)

/// NEW
bool IInputItem.ValidProvider(IOutputItem iProvider, out IDescribable[] reasons)
bool IOutputItem.ValidConsumer(IExchangeItem iInputItemOrDecorator, out IDescribable[] reasons)

enum should be 1,2,4,8 etc so can be bitted

					/* TODO new state in Standard WaitingForFinish
					 * Cant call finish here as might clear up resources
					 * associated with output items buggers etc.
					 * so just need to return and wait for external
					 * controller to call finish
					 * 
					 * Desirable to have a new state
					 * LinkableComponentStatus.WaitingForFinish
					 * to make this clear in UI's etc.
					 * 
					 * For now will use Finishing
					 */
					 
					 
					// TODO Note I prefer WaitingForData before Updating

2.6 Test cases

2.7 General introduction

2.8 Linux

3. Review of the implementation

3.1 SDK + standard

3.2 Already migrated model

3.3 Running of the connected models from GUI

3.4 Pending tasks

4 Plan of the Ver. 2.0 release

4.1 Alpha for review (documentation, announced on the OpenMI Web)

4.2 Beta + new release of the documentation

4.3 Final delivery -+ text for the Life project report

5 Necessary changes to the Standard

Suggestions based on the implementation. Only if really needed !!!!!!

Additional status for LinkableComponent.Status

The status 'computation done, but not yet finishing' can not be speficied. This occurs when one component in a composition is done, while others are not. The deployer will call Finish when all components are done. Suggestion: add the status WaitingForFinish.

IOutputItem.Decorators on

During a plenary Skype meeting one of the questions was whether the list of added decorators should be public or not (see). During the discussion it was suggested to put the list of decorators not on ILinkableComponent, but on IOutputItem. This indeed is very useful, because then the
List<IOutputItemDecorator> IOutputItem.Decorators
property facilitates update the decorators in the right order.
It can be discussed whether the AddDecorator and RemoveDecorator methods then also should be moved from the LinkableCompent to the OutputItem.

Time Horizon / Spatial domain (back) on ILinkableComponent

We removed TimeHorizon from ILinkableComponent. However, configuration time it still would be handy, as well as run time, to display a progress bar.
Of course, there now is IExchangeItem.TimeSet.TimeHorizon, but the TODO in the documentation of ITimeSet.TimeHorizon shows that one could easily (and most probably would preferably) explain this as the time horizon of the available resp. required time.
However, exactly the same can be said for the spatial domain 'horizon' of a component. Where can the component do its work, where are things available or required.

To handle the issues mentioned above, the following is suggested:

Introduce something like:

 
  IExchangeItem ILinkableComponent.Domain { get; } 
  // with: 
  myLc.Domain.TimeSet.TimeHorizon // the temporal domain 
  myLc.Domain.ElementSet // the spatial domain. 
  

Or maybe better introduce a specific interface for it:

 
  IDomain { 
  ITime TimeHorizon; // the temporal domain 
  IElementSet Area; // the spatial domain 
  } 
  

The myComponent.Domain, and thus the I(In|Out)putItem.Component.Domain, then specify the applicability of items, configuration time.

The actual runtime situation is then presented by the current anItem.ElementSet and anItem.TimeSet, i.e.:

• anItem.ElementSet: for what location(s) are the values required (input) or available (output)
• anItem.TimeSet.Times: for what time(s) are the values required (input) or available (output)
• anItem.TimeSet.TimeHorizon:
  a. InputItem: for what time span may an input item require values (thus covering 1.4's EarliestInputTime mechanism):
  b. outputItem/decorator: in what time span can I provide values
  Additional definitions:
  . TimeSet.Times == null : time independent item
  . TimeSet.Times.Count == 0 : time independent item, but no values available yet.
  . TimeSet.TimeHorizon == null: time independent item
  . TimeHorizon.StampAsModifiedJulianDay == Double.NegativeInfinity : far back in time
  . TimeHorizon.Duration == Double.PositiveInfinity : far in the future

Mechanism to indicate whether an output item has up to date data or not.

This mechanism, e.g. a flag needsUpdate (the inverse of what was once introduced as isAvailable) is needed for the loop driven approach. However, it is also useful for optimization in the pull driven approach. If nothing has been changed at the providing side, the previous values can be used.
To be discussed at the meeting.

• Gena: Add a flag on IExchangeItem.IsSynchronized (can be used or another thread / component is still modifying it, if it is in synchronized state), multiple-thread related. Probably name can be also IsAvailable.

6 Public talk

We need to discuss extend of the meeting and more detail agenda. Our primary focus for the meeting need to be create progress especially in the version 2.0 documentation. In the week starting 24.8 we need to indicate content of the planed talks - provide to the Peter enough time to invite peoples.