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 (API). 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. For more complete linkages, your API should also contain value accessors and mutators so that an application can query and change state variables of your model.

The IRF Interface

Numerical models can generally be subdivided into three phases: set up, execution, and teardown.

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:

int init_my_model ( char **strs );

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:

int run_my_model (double time);

Model Termination (the finalize step)

Things to include:

Things not to include:

Sample interface:

int finalize_my_model (void);

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,

CALL model init function

REPEAT
  CALL model run function for some duration
UNTIL time < end time

CALL model finalize function

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,

DISPLAY GUI to collect initialization data
CALL model init function

REPEAT
  CALL model run function for some duration
  PRINT data to an output file
  DISPLAY data to screen
UNTIL time < end time

PRINT final data to file
CALL model finalize function

Model Accessors and Mutators

The IRF interface described above allows a calling application to control the execution of your model. The application may be the one that you have already written. In which case, the new interface has really just acted to clean up you code and hopefully made it easier to maintain. However, the new interface has also made it easier for someone else to take you model and wrap it inside another application. Because the IRF interface provides a way to control the model's execution, ultimately the new application will be similar to yours. What could do though is put a completely new user interface on your model. For instance, someone could wrap your model in an application that reads input from a new file format, or maybe from a graphical user interface.

You may have noticed though that there are still a couple of things missing from this interface that would be useful. For your model to be able to meaningfully communicate with other models, you should be able to exchange values that your model calculates. Furthermore, your model should provide a means for another model to set particular values of itself. One way of doing this is through a getter and setter interface. As we have seen, a barebones IRF interface is certainly valuable but the more getter and setter methods your model has, the more useful it will be in linking with other models.