Help:IRF Interface

CSDMS Model Interface Standards

For you model application to become a component that can be linked in meaningful ways to other model components, it must have a application programming interface. CSDMS asks model contributors to provide a minimal set of functions that allow a calling program to control the component's execution. The minimal set of interface functions would be those that initialize, run, and finalize a component model - the IRF interface.

Model Set Up (the initialization step)

Before a model enters into its time-stepping loop, it will usually execute a set of commands necessary to set up the subsequent model simulation. This can be thought of as the initialization step - the lines of code before the time loop. For an application to

Things to include in your model's initialization function:

• Initialize variables.
• Allocate memory.
• Open temporary files
• Stuff that is done once, and is before the time loop.

Things not to include in your model's initialization function:

• User interfaces. Your initialization function should not include a user interface (graphical user interface, or a command line interface, for example). This should be taken care of by the calling application.

A typical interface for model initialization: <geshi lang=c> int init_my_model ( char **strs ); </geshi> In this case the initialization function takes an array of strings as input. The strings might be names of input files to read from, or could be key/value pairs that set particular model variables. These are just suggestions. It may make sense for you model to initialize itself in a somewhat different way. The main point is that you provide an entry point to your initialization step and document your particular interface.

Model Execution (the run step)

Your model's execute step should run your model for a particular amount of time (simulation time, that is). Generally speaking, this will be the lines of code that are within you time loop.

Things to include:

• Code that updates the state of you model with time.

Things not to include:

• User interfaces. This could include, for instance, plotting of the model's state as it's running. These things should be taken care of by the application that runs your component.
• Writing data to output files. This is just another interface and the application should do this.

Sample interface: <geshi lang=c> int run_my_model (double time); </geshi>

Model Termination (the finalize step)

Things to include:

Things not to include:

Sample interface: <geshi lang=c> int finalize_my_model (void); </geshi>

Your Model Application

Notice that the above interfaces have excluded any user interfaces. As we've stated above, the application should take care of user interfaces. With the above interfaces, your model application will consist of a call to your initialize function, followed by your run function (possibly wrapped in a for loop, say), followed by a call to your finalize function. Between these calls, will be your user interface. The particular user interface that you decide to use is up to you.

Without any user interface, your application might look someting like the following pseudocode, <geshi> CALL model init function

WHILE time < end time

 CALL model run function for some duration

CALL model finalize function </geshi> Since an application is not of much use if it doesn't interface in some way with a user, you need to add a user interface. The pseudocode for this might look like, <geshi> DISPLAY GUI to collect initialization data CALL model init function

WHILE time < end time

 CALL model run function for some duration
 PRINT data to an output file
 DISPLAY data to screen

PRINT final data to file CALL model finalize function </geshi>