Demonstrator client-server architecture

ECOSIM Telematics Applications Project:
Deliverable D04.04

Architecture Description and Assessment Methodology

Keywords: Architecture, hardware, software, data requirement, networking, client-server, http. DRAFT Release 0.3, 3 November 1997 Author: Kurt Fedra

Systems Architecture

The ECOSIM demonstrator is based on a client-server architecture, taking advantage of the http (hypertext transfer) protocol. The main server provides the basic user interface and controls the user dialogue, displays information, and connects to external information resources (monitoring data, data bases, simulation models) as required.

This communication is based on the public http protocol, and can be based on the Internet or dedicated connections (such as ISDN phone lines) for the physical communication layer. This protocol also forms the basis of World Wide Web browsers like Mosaic or Netscape. The following diagram summarizes this architecture:

Diagram

Client/server structure

The ECOSIM demonstrator will be implemented within an object-oriented paradigm. As the central element, OBJECTS have encapsulated methods available to access and utilize information resources

The information resources are provided by several logical servers in the distributed ECOSIM design, including:

database servers that store and convert the various data streams, primarily from monitoring networks as well as the simulation model results; using a common data format like HDF in particular the latter will also facilitate the publication of this information through the Internet/WWW.
model servers that are responsible for the execution of the numerical models and may be implemented on parallel high-performance computers or workstation clusters;
GUI server which includes the embedded visualization tools, GIS, hypertext, all resident in the main ECOSIM server.

Logical clients include the main ECOSIM server (that is a client for the data base and model servers); they also include the (distributed) consoles (workstation consoles, X terminals, or PC with browser software) that can access the ECOSIM (GUI) Server. Unfortunately, the terminology is not consistent in that within the context of the X Windows system, server refers to the display system whereas the client denotes the actual application program that provides the data stream (requests sent to the server) displayed by the server.

Model Integration Strategy

The model integration strategy is based on

a common development approach and methodology
a common object oriented design and development strategy;
a set of standardized data formats including the Hierarchical Data Format (HDF)
and for the actual communication between the distributed modules of ECOSIM, on the http (Hypertext Transfer Protocol), which is available in the public domain, e.g., in the CERN http server libraries.

The basic sequence of a remote model call looks like this:

The ECOSIM server calls

a communication routine with two call-back functions (out & in) as parameters, this makes use of the CERN http server library: the out-call-back function provides the parameters
which calls a remote http server
which calls a remote cgi program (local on the remote machine, see example below) which reads parameters sent by the out-call-back function, passed by the CERN library & http server
This cgi program invokes the external model (see pseudo-code example below) and sends back results to the
remote http server who believes the result is a http page because of the Content-Type record, see below)
this connects back to CERN library in-call-back function
that sends the result to the ECOSIM server and returns control to this server for interactive analysis and display, etc.

Example cgi code:

   #include 
   main () {
       char    buf[256];
       int     Nbytes;
       FILE    *INFILE, *OUTFILE;
       fprintf (stdout, "Content-Type: text/html\n\n");
       /* caller receives notification of HTML page coming */
       /* INFILE is a local scratch file for model input .... */
       INFILE = fopen("mode_input","w");
       while (fgets (buf, 256, stdin)) {
               fprintf (INFILE, "%s", buf);
               if (!(strncmp (buf, "END", 3))) break;
       }
       /* all input received, ready to run the model */
       /* with run_model()                           */
   
       run_model(WHATEVER); /* with error handling, of course */
   
       if(( OUTFILE = fopen("model_output","r") == NULL) {
           printf("can't open model output\n");
           fprintf (stdout, "Content-Length: 0 \n\n",);
       } else {
          Nbytes = get_size(OUTFILE);  /* size of the message body */
          fprintf (stdout, "Content-Length: %i \n\n",Nbytes);
         }
          while (fgets (buf, 256, OUTFILE)) {
               fprintf(stdout,"%s", buf);
               if (!(strncmp (buf, "END", 3))) break;
               /* used to signal the receiving process 
                  end of data transmission */ 
          }
   }

High-level Communication Structure

The communication between the external model and the client will be controlled by an object hierarchy which defines the inputs to and the outputs from the model.

It will also drive the interface components of the demonstrator by defining what the user can edit and what the ranges of the parameters are for which the model is guaranteed to work.

This key element is the following Generic Object Definition:

 
           DEFOBJECT
              NAME id
              URL  url1
              EXP  url2
              DESC
                Descriptorname Value
                Descriptorname Value
                ....
              ENDDESC
              TIMESERIES
                TimeseriesRef
                TimeseriesRef
                ....
              ENDTIMESERIES
              MATRIX
                MatrixRef
                MatrixRef
                ....
              ENDMATRIX
              OBJECTS
                ObjectName
                ObjectName
                ....
              ENDOBJECTS
           ENDDEFOBJECT

where

NAME the unique identifier of the object ( mandatory for all objects)
URL the URL of the model to run, ie., the network path of the executable (or cgi script) implementing the model (only mandatory for the model object)
EXP the URL where background information (in HTML format) on the model can be obtained (optional)
DESC ... ENDDESC here one or more descriptors can be associated with this object and initialized with the specified values
TIMESERIES ... ENDTIMESERIES references to time series will be implemented here (option not yet supported)
MATRIX ... ENDMATRIX references to matrices will be implemented here (option not yet supported)
OBJECTS ... ENDOBJECTS references to objects which belong to this object

The top level object of the hierarchy must contain the model specification, ie., model name and URL, general model parameters as descriptors, references to the scenario objects, and a specification of the model results. Eg., the top level object of the AirWare model is defined as follows

 DEFOBJECT
 NAME AirWare
 URL  http://www.ess.co.at/~air/AIR
 EXP  http://www.ess.co.at/~air/airman.html
 DESC
 x_Gridpoints 100           # number of grid points in x-direction (nx)
 y_Gridpoints 100           # number of grid points in y-direction (ny)
 x_Dimension   50           # grid extension in x-direction [m]    (dx)
 y_Dimension   50           # grid extension in y-direction [m]    (dy)
 Orography      0           # 0: orography NOT taken into account
                            # 1: orography is taken into account
 ENDDESC
 OBJECTS
 WeatherScenario
 EmissionScenario
 ENDOBJECTS
 MATRIX
 ConcentrationMatrix
 ENDMATRIX
 ENDDEFOBJECT

The Scenario Objects then contain the scenario parameters the model expects to get as inputs.

 DEFOBJECT
 NAME WeatherScenario
 URL
 EXP
 DESC
 Stability_Class  1         # Pasquill stability class (A=1,...,F=6)
 Wind_Speed       2         # wind speed at reference height [m/s]
 Wind_Direction  90         # direction from which the wind is blowing,
                            # measured in degrees, counter-clockwise with
                            # East=0, North=90, West=180, South=270
 Ref_Height      10         # reference height for wind speed measurements [m]
 Temperature    250         # ambient air temperature [K]
 Mixing_Height 1000         # mixing height (height of inversion layer) [m]
 ENDDESC
 ENDDEFOBJECT
 
 DEFOBJECT
 NAME EmissionScenario
 URL
 EXP
 DESC
 Decay         xx           # decay constant of the pollutant considered [1/s]
                            # decay = ln2/thalf (thalf ... half-life time)
 
 PointSources   20          # number of point sources
 ParticleTypes   5          # number of types of particles
 ENDDESC
 OBJECTS
 PointSource-01
 PointSource-02
 PointSource-03
 ...
 PointSource-20
 ParticleType-1
 ParticleType-2
 ...
 ParticleType-5
 ENDOBJECTS
 ENDDEFOBJECT
 
 DEFOBJECT
 NAME PointSource-01
 URL
 EXP
 DESC
 X-Coord     100             # x-coordinate of point source [m]
 Y-Coord     200             # y-coordinate of point source [m]
 Emission     50             # emission rate [g/s]
 StackHeight  20             # height of stack [m
 Diameter      3             # inner diameter of stack [m]
 Velocity      5             # stack exit velocity [m/s]
 Temperature 300             # stack exit temperature [K]
 ENDDESC
 ENDDEFOBJECT
 
 DEFOBJECT
 NAME ParticleType-1
 URL
 EXP
 DESC
 MassFraction xx            # mass fraction of particles 
 Velocity   xxx             # mean settling velocity [m/s]
 ENDDESC
 ENDDEFOBJECT
 
 DEFOBJECT
 NAME ConcentrationMatrix
 URL
 EXP
 MODELOUTPUT                # concentration at gridpoint m [ug/m3]
                            # where   m = (j-1)*nx+i
                            # and gridpoint m has the coordinates
                            # x = (i-1)*dx   i = 1, ..., nx,
                            # y = (j-1)*dy   j = 1, ..., ny
 ENDOBJECT

In the objects the model inputs and outputs are referred to as descriptors which have to be defined in a separate file using the following simplified descriptor syntax:

 DESCRIPTOR
 descriptor_name
 T  descriptor_type
 U  unit
 V  range / range / range / ...
 Q  question
 ENDDESCRIPTOR

Examples for descriptor definitions in in the AirWare model are

 DESCRIPTOR
 Air_Temperature
 T S
 U C
 V extremely_low [-20.0,-10.0, -5.0] /
 V very_low      [ -5.0,  0.0,  2.0] /
 V low           [  2.0,  5.0,  8.0] /
 V medium        [  8.0, 10.0, 15.0] /
 V high          [ 15.0, 20.0, 25.0] /
 V very_high     [ 25.0, 30.0, 40.0] /
 Q What is the current ambient Air Temperature
 Q in degree Celsius (Centigrade) ?
 Q \n \n
 Q Ambient Air temperature together with the flue gas exit temperature
 Q is used to determine plume rise or effective stack height,
 Q resulting from the buoyancy of a gas warmer than its surrounding.
 ENDDESCRIPTOR
 
 DESCRIPTOR
 Stack_Height:
 T S
 U m
 V Very_small[0,10] / Small[10,30] / Medium[30,50] /
 V Large[50,75] / Very_large [75,200] /
 Q What is the stack height?
 ENDDESCRIPTOR
 
 DESCRIPTOR
 Exit_Velocity:
 T S
 U m/s
 V Very_small[1.0,2.0] / Small[2.0,3.0] / Medium[3.0,7.0] /
 V Large[7.0,13.0] / Very_large [13.0,27.0] /
 Q What is the exit velocity of the flue gas ?
 Q \n \n
 Q Exit velocity, together with exit temperature is used to
 Q estimate plume rise or effective stack height.
 ENDDESCRIPTOR

The ranges of the descriptors define the range of valid values (from the point of view of the model) for each parameter of the model and will be used in the editing functions of the client. This forms the basis for coordinating the editing of the parameters on the client and which values the model on the server expects for its input parameters.

Also, the sequence in which the input values are sent is implicitly defined in the structure by the sequence in which the descriptors are listed in the DESC ... ENDESC blocks, and down the hierarchy following the sequence which is defined in the OBJECTS ... ENDOBJECT blocks, and there again in the DESC ... ENDDESC blocks, and so on.