Modeling Projects

This tutorial section explains a Modeling Project within OMS.

Modeling Project Explorer

Modeling Project Structure

A modeling project contains resources of the following categories

• Documentation - Additional descriptive information about the project.
• Input- Data that is being used as input for applications
• Output - Data that is produced by applications
• Components - Software units (sources) that have a well defined purpose and conceptual domain and are independent from any specific application context.
• Models - Assembly of components and/or libraries that perform a set of tasks
• Simulations - Assembly of models, execution type, input/output data, and analysis for a specific purpose and domain
• Analysis - Creates derived information and views based on input/output data

A Modeling Project in the OMS context is an organized structure to help manage component and model development along with data analysis. In a Modeling Project, files such as component sources, component executable, libraries, models, data, etc are organized in a folder structure. Projects are self-contained. They reside on a local hard drive and can be managed using the OMS Modeling Project explorer. The project explorer can be activated using the menu Window | Projects. The Project explorer shows a list of active projects in OMS.

Figure: Modeling Project Explorer

The Figure above shows the project explorer with one active project named gov-usgs-thornthwaite, located in c:/omswork. The global tool bar allows the management of the main project. More than one project can be open at any time, one project can be the main. The main project is indicated by its bold project name.

Figure: Project Toolbar

The tool bar icons (from left to right) have the following project related actions as shown below

1. Creates a new File in the active project. The type of the file will be selected from a template.
2. Creates a new project, and adds it to the project explorer.
3. Opens an existing project. Maintains a list of previously opened projects.
4. Saves all modified files in the project.
5. Builds required files in a project.
6. Cleans and Builds the project resources.
7. Executes the selected model
8. Debugs the selected model (Currently not supported)
9. Creates a library from this project's components.

Creating a New Modeling Project

OMS provides a simple wizard for creating a new modeling project for a new modeling project. It can be invoked using the New button of the project explorer. The wizard provides two steps.

1. Select the directory name for the new project. The dialog will ask for the name and the location of the new project. Type in the parent directory where you want the OMS project in the File Name text entry box in the above dialog. Type in the name of the project in the Project Name text block. The resulting full pathname to the project files from the above example above would be c:\omswork\master.
   
   
2. Select a full qualified name for the project. This is being used as the main package name for the components in this project. Components usually reside in a 'package' or 'namespace', which could have multiple levels, separated by '/'. Each name within this path represents a folder underneath the src directory of the project. The default package name is the same as the project name.

Open an Existing Modeling Project

An existing project can be added to the Project Explorer to be used as an active modeling project. The open project icon in the Modeling Project Explorer tool bar allows the selection of a project folder to be opened. Only valid OMS project folders can be selected and opened. Such a project folder is indicated by an overlaid OMS icon on the folder icon.

Figure: Open Modeling Project Dialog

After selecting the Open button the project will be added to the Modeling Projects Explorer.

Removing a Project from the Project Explorer

Projects can be removed from the list of open projects shown in the project explorer. Removing from this list will not physically delete the files and folders from the hard drive. A project can be added back into the project explorer by open it again. Right click on the project node and select Close Project.

Compiling, Building, Cleaning Project Resources

Component Resources are managed within the Projects Explorer. All Component get compiled when the Compile button is pressed. This includes all Java, C, and FORTRAN sources. The build products will be stored in the build folder of the project.

A compile always works incrementally. Only changed component will be compiled. If all components should be build, regardless of their state, the Build button should be used.

The Clean action cleans all build products within one project. All component class files, object file, and libraries will be deleted.

Note: Icons for compiling, building, cleaning, deploying and closing a project are sensitive to the selected project. The project or one of its folders or file has to be selected to make these actions available.

Figure: Build process output

The progress and result of the compile and build process will be shown in the Output Explorer at the bottom of the User interface. If the compilation of the sources fails, the errors will be printed out according to the compiler and linker being used.

Deploying Components to the Component Library

The Deployment button manages the deployment of the projects components into the component library. After a successful build and deployment of a set of components a new library entry appears in the Component Library Explorer.

It is required to add all components of a project to the component library, if they should be later used for model building. If a component is not shown in the Component Library Explorer, it cannot be used in a model.

The component library explorer can be activated by selecting the menu item Windows | Component Library. It shows all component libraries which are ready for model development. Component Libraries are organized as jar Files. Jar stands for Java archive and contains all resources required for model integration.

Figure: Component Library Explorer

Component can be viewed by jar file they are in (default view), by name, or by category they are belonging to. There are also Icons in the Component Library Toolbar for updating the view and showing the full qualified name.

Modeling Project Resources

A project has a certain folder and file structure. It provides a framework where a modeler can manage source or data files. A project can be anywhere on a local file system. The directories in a project have the following meaning:

/src

contains component source files, such as Java, FORTRAN, C++ or C files. The source files are organized in folder according to Java packaging requirements.

/build

contains component class files and dynamic loadable libraries and build products in general.

/test

Contains tests for component files. The /test folder structure should mirror the one in /src.

/lib

Contains libraries the components are depending on such as visualization packages.

/doc

Contains documentation about the project,

/data

the data folder contains data which is being used by the model(s) developed in this Project.

/nbproject

Contains configuration data for projects such as project build properties and other internal build files.

The directories except the nbproject directory are empty. They are place holder for specific resources such as source files, data files, or libraries. The directory nbproject is different. It contains files that the OMS build system depends on; these files should never be edited or deleted.

The Build File (build.xml)

A build file has so called targets, which represent a certain build action. By opening a build file in the Project Explorer the targets gets visible as sub nodes underneath the 'build.xml' node. They can be executed by double clicking on their node. The Figure above shows the execution of the make target, which deletes all executables and temporary files from the project. A target gets executed by double clicking on its node or selecting the node and press the key F6.

The build.xml file has three default targets:

make

incrementally compiles and links Java classes or native sources into executables.

build

performs a fresh compile on all files and links the executable.

clean

cleans up all executable and temporary files.

jar

creates the component jar file.

A build.xml file can be extended by adding more targets for more specific tasks. It is an XML file and can be edited within OMS or externally using any text editor. A comprehensive reference for creating such build files can be found at http://ant.apache.org/manual.

Build File Properties (build.properties)

The build.properties file resides in the project folder. It contains adjustable settings to control the build process such as compiler flags and other control elements. Comment lines starting with an '#' at the beginning of a line.

# Native Settings
CC.files          = **/*.c
CPP.files         = **/*.cpp
FTN.files         = **/*.for, **/*.f90, **/*.f, **/*.f77
CC.bridge.files   = src/**/*_Bridge.C, nbproject/oms.C
CC.bridge.defines = NORMAL
OBJ.files         = *.o

# Java compiler flags
javac.deprecation = false
javac.debug       = true
javac.source      = 1.5
javac.target      = 1.5
javac.verbose     = false

The build.properties file is always specific to the modeling project it belongs to. Compiler/Linker tools and their options can be specified. Especially for native component development these settings are imported to adjust to C/C++ and FORTRAN compiler to be used. The default settings are given for the GNU Compiler Collection tools for compiling C/C++ and FORTRAN using the Cygwin environment. Most of the settings are self explain