You are here: Manual / PropagationModels / User Defined

---

Creating a propagation model plugin

A video decribing how to install the plug-in is available here (8 MB - note: the sound is fading towards the end.). Note that the new embeddement feature is not presented in the video.

Introduction

The SEAMCAT-3 has implemented a new means of programming the User-defined propagation models. The plugin concept was chosen to avoid the inherent format limitations of the original SEAMCAT-2 interface and make the user-defined model to work as fast as any in-built model. With the plugin propagation model, the user may define very complex propagation modelling using standard Java programming language.

The very detailed and illustrated description of programming and connecting plugins with user defined propagation model is provided below on this page.

Environment

Before you can start developing SEAMCAT post processing plugins you will need to ensure that your system has been correctly configured.

Information on how to do this is located in the Basic Enviroment Setup section.

Creating the plugin

To create the plugin you create a file called .java and place it in a directory of your choice, eg. C:\Seamcat\plugins and then you open this file in your favorite texteditor.

In this file you paste the contents here below to create the skeleton of a plugin.

import org.seamcat.model.propagation.PluginModel;

public class MyPlugin implements PluginModel {
        
       public double evaluate(double frequency, double distance, double TxHeight,
                                           double RxHeight, int generalEnv, 
                                           double param1, double param2, double param3) {
                
       //Your model implementation goes here
       }
}

This is the base skeleton you need to implement in order to create a Seamcat plugin. When creating the java-file, it is important to observe the java-code conventions, ie. the name of the class must match the name of the java-file, ie. the class MyPlugin must be defined in a file called MyPlugin.java, also it is recommended to start the classname with a capital letter.

Now you are ready to implement the evaluate method with your own mathematical functions.

Sample plugin

The following is a small sample plugin to show how to create the plugin and how to use System.out.println for debugging purposes.

This sample plugin is an implementation of the DualSlope Pathloss model.

import org.seamcat.model.propagation.PluginModel;

public class DualSlope implements PluginModel {
 public double evaluate( double frequency, double distance, double TxHeight, double RxHeight, int generalEnv, double REFERENCE_DISTANCE, double PATH_LOSS_COEFFICIENT, double param3) {

  double loss; 
  //Convert distances into meters 
  distance *= 1000; 
  REFERENCE_DISTANCE *= 1000; 
  double l = 300 / frequency; 

  if ((distance) < REFERENCE_DISTANCE) { 
   loss = 20 *Math.log10(l / (4* Math.PI * distance)); 
   System.out.println("Distance is below reference distance and loss is " + loss + " dB"); 
  } 
  else { 
   loss = 20 *Math.log10(l / (4* Math.PI *REFERENCE_DISTANCE)) + 10* PATH_LOSS_COEFFICIENT* Math.log10(REFERENCE_DISTANCE / distance); 
   System.out.println("Distance is above reference distance and loss is " + loss + " dB"); 
  } 

 loss=(-1)*loss;

 return loss; //losses are positive value
 } 
}

When running the above code 10 times, you will see something like the following in the Java console (depending on how you configured the run), which should give you an idea of how you can use System.out.println statements to debug your plugin if the plugin doesn't produce the results you were expecting.

You should remove any "System.out" statements before using your plugin in actual simulation, as these will clutter logfiles and slow down simulation speed signifigantly.

How to compile the plugin

In the following, it is assumed that you have set your PATH environment properly. To set the PATH environment follow the explanation as described in Basic enviroment setup. Make sure that the file "seamcat_needed_for_plugin.jar" and your plugin "DualSlope.java" is in the same folder (for this example), if this is not the case, you need to change the paths in this section accordingly.)

Open a dos-prompt window and select the folder where your plugin is. for instance seamcat\plugins folder. Here you enter the command "javac -classpath seamcat_needed_for_plugin.jar DualSlope.java". This will compile your plugin so that it is ready to be added to the Seamcat application.

_{NOTE: Remember that the name of the file should be the same as the name of the class. I.e. the DualSlope class should be defined in DualSlope.java.}

_{If the compiler complains about problems with your plugin, you need to fix these and try to compile again.}

How to add your plugin to SEAMCAT (with embeddement)

Once you have compiled your plugin successfully, you will find a .class file in the same directory as your java file.

You can embed your propagation model plugins so that you can distribute your workspace with your plugin. This increases the flexibility in exchanging workspaces within the SEAMCAT community.

You need a copy of the seamcat_needed_for_plugin.jar in the Seamcat directory (%USER_HOME%seamcatplugins).

The following step-by-step procedure presents an example on how to embed propagation model plugin library. We are using the JTG5-6 model (available at http://tractool.seamcat.org/wiki/Manual/PropagationModels/JTG56):

1. The .class files have to stored in a .zip or a .jar file anywhere you want on your machine.
2. In SEAMCAT, press Library -> Propagation model plugins -> Add ->

3. Select the .jar or .zip file to be embedded in your library. You will see that the name of the file you have embedded is appearing under the choose button.

4. Name is a name to identify your plugin.
5. Description is a short description of your plugin (optional).
6. Fully Qualified Classname is the fully qualified classname of your plugin. In Fully Qualified Classname form write: JTG5-6_ver2 (it should appear as you type and the red background should disappear). The Name/Reference will automatically update as you type in the Qualified Classname form. Note that you can edit this field if you want to.

7. when you click ok, you will see that the propagation model that you have selected is embedded. This will allow you to share your workspace with others without sending separately your propagation model.

8. You can now set your propagation model in the victim or the interfering link. You do not need to close and relaunch SEAMCAT.

Note that SEAMCAT will automatically save the .jar or .zip file on your “plugin” directory.

Backward compatibility with 3.2.2 of embedded propagation model plugins

Workspaces which have embedded propagation model plugins using version 3.2.2 will automatically be detected by SEAMCAT and converted to a readable format to version 3.2.3. It consists of a mere conversion from a .class format to a .jar format. The calculation of the propagation plugin is not touch.

Requirements to embeddement

In addition to the existing requirements for plugins, embedded plugins will only work if:

• The plugin must only refer to classes which are in the SEAMCAT classpath, not another plugin. This also goes for the class definitions, ie. extended classes, implemented interfaces, generics etc. A simple rule to stick to is to only use standard java functionality and SEAMCAT functions.
• The plugin must use the default package (meaning that the "package"-statement should be omitted)

In the unlikely event that SEAMCAT fail to upload the embedded file, the SEAMCAT user will be prompted with the following error message as shown below.

How to add your plugin to SEAMCAT (without embeddement)

If you do not want to embed your plugins into your workspaces, copy the .class file to your Seamcat directory (%USER_HOME%seamcatplugins). You need to do that before you launch SEAMCAT.

Remember that if you have chosen to use a package for your plugin, you must recreate the package structure under the plugins directory. If you dont know what that last meant, then you probably didnt use a package and can ignore it.

1. Keep the copy of the seamcat_needed_for_plugin.jar in this directory.
   
   

2. Next start up the Seamcat application and add the plugin.
3. Next fill out the information about your plugin.

4. Now click OK and Close SEAMCAT.
5. Restart SEAMCAT and your plugin should be ready for action.

How to test your plugin

You can test any of your plugins. Go to the following http://tractool.seamcat.org/wiki/Manual/PropagationModels/HowToTestPropagationModel to get more information.

Available Mathematical functions

Please go to the end of the following page http://tractool.seamcat.org/wiki/Manual/Library/Plugins/PostProcessing to get more information on the Mathematical functions.

Problems

Q: Why do I get an error telling me the class file has a wrong version ?
A: If you get an error like the one below, it is because you are trying to compile the plugin using a java-version earlier than 1.5.0.

Check your PATH environment variable if there is a reference to a directory containing another javac.exe. Alternatively use full path to the javac compiler when compiling the plugin.

MyPlugin.java:1: cannot access org.seamcat.mathematics.Mathematics bad class file: 
..libseamcat_needed_for_plugin.jar org/seamcat/mathematics/Mathematics.class) 
class file has wrong version 49.0, should be 48.0

Q: Why do I get an "The specified class failed to load" when trying to add a new plugin ?
A: Check your %HOME_DIR%seamcatseamcat.log file. If you see an "java.lang.NoClassDefFoundError: org/seamcat/model/propagation/PluginModel" error message, then you have forgotten to copy the seamcat_needed_for_plugins.jar file to the plugins dir. Copy this file and restart Seamcat.

Q: Why do I get an Unknown command error when trying to compile my plugin ?
A: You didn't add %JAVA_HOME%bin to your PATH environment variable.