• View
• Edit
• History
• Print

ModelCustomCode

The last subpanel is where the user can declare Java methods of his own.

The statements that are entered in the Initialization panel, the Evolution panel, and the Fixed relations panel are inserted into methods of the Java code that is created by EJS. On the custom methods panel the user enters complete methods. Another difference: the methods that are declared in the custom methods panel are executed only if they are invoked from another part of the simulation.

One reason for creating a custom method may be to organize calculations. An elaborate mathematical expression can be moved to a custom method that is invoked from the location where it is needed, to help make the code more readable. For another reason, if the same calculation is performed several times, with different variables as input each time, then with a suitable custom method the same code can be reused. Finally, the most advanced use for creating custom methods is to extend the functionality of EJS.

Function

If you have an elaborate expression, such as {$$ x_i = f(x_1,x_2,\dots,x_n) + g(x_1,x_2,\dots,x_n) + h(x_1,x_2,\dots,x_n) $$} The method that has as its body that kind of expression is called a 'function'. We must then indicate the type of the value that is returned, which can be any valid Java type, either simple or dimensioned. The execution of the method must then end with a return sentence that indicates the value effectively returned.

Reusing code

Example: a 2D model with two particles, the coordinates of their positions are (x1,y1) and (x2,y2) respectively. For both particles we want to calculate the distance to the origin of the coordinate system. Using parameters the same code can be used for both (x1,y1) and (x2,y2). The method is then coded as follows:

public double calcRadialDist (double xVar, double yVar) { return Math.sqrt(xVar*xVar + yVar*yVar); }

Here, declaring 'xVar' and 'yVar' instructs Java to let the method accept input parameters. The following Java statement obtains the radial distance of particle 1 (rd1), by invoking the method with x1 and y1 as parameters:

rd1 = calcRadialDist (x1, y1);

Java will then perform a substitution, executing the method as if it had been coded as follows:

public double calcRadialDist () { return Math.sqrt(x1*x1 + y1*y1); }

In Java terminology this substitution scheme is called 'passing a variable'. The requirements are that the number of parameters must match, and their types must match: if they don't the compiler will report an error.

Another situation where you can opt to write code in a custom method is when an expression in the ODE editor is rather elaborate. Actually, in the case of a custom method that is to be invoked in the ODE editor the variables must be passed to the custom method. The reason for that is that the numerical analysis algorithm evaluates the expressions for intermediate values of the variables, to compute a weighed average. If the variables are not passed to the custom method then these intermediate values won't be used. By passing the variables the method is executed as if it was coded on the Evolution panel itself.

The options and requirements when declaring a method.

When creating a new page in this panel with the name, say, "myMethod" EJS will give you a page with the structure of a custom method.

For the method's name the same rules and conventions apply as for naming variables.

The term accessibility refers to which other parts of the simulation can use the method. If the method is declared as `public' then the method is universally visible. It can be used anywhere in the model and in the view. It also results i the method being visible from outside the simulation by using JavaScript. If the method is not declared as public then the method can only be used inside the model. (The accessibility keyword for this is private. Also, when no accessibility keyword is declared Java defaults to treating the method as 'private') There is actually no powerful reason that prevents us from declaring all our custom methods public, except perhaps reducing the offer to end users who don't know what every method does and for whom it could even be confusing to see so many methods available.

A method that doesn't return a value is of type void. For instance, a method may check for a condition, and pause the simulation if that condition is met. Such a method processes information, but it does not return a value, and the designated type of such a method is void.

If the method returns a value the type of the value (double, int, boolean, string, Object) must be declared.

If the custom method is coded without declaring any parameters the list of parameters is empty: (). The parentheses must allways be there, either with some parameters or as an empty list.

Properties of the custom method panel

On the same subpanel more than one method can be declared.