## BASIC

The BASIC package of NM Dev has the following list of features.

## Calculus

• finite difference
• differentiation using Ridders’ method
• derivaties of functions for:
• Beta
• Beta Regularized
• Erf
• Gamma
• Gaussian
• multivariate differentiation:
• (bordered) Hessian
• gradient
• Jacobian
• Riemann integration
• Riemann integration using substitution rules:
• Double-Exponential rule
• Exponential rule
• Power law singularity
• Map to the Standard interval
• integration using Romberg’s method
• integration using Newton-Cotes formula
• Simpson’s rule
• Trapezoidal rule
• Midpoint rule
• integration using Gaussian quadrature
• Legendre polynomials
• Chebyshev polynomials
• Laguerre polynomials
• Hermite polynomials

## Coding Tools

To set up the coding environment for a new NM Dev project, please follow the following steps.

## JDK

NM Dev is a Java based code. Before we can code using the library, we need to install the latest Java Development Kit (JDK). If you skip this step, you can download it together with NetBeans in the next step.

## NetBeans

NetBeans is our preferred IDE for Java programming. You may download and install JDK and then NetBeans. Or you can download “NetBeans with JDK” directly.

NetBeans can be downloaded from this link. If you have no Java programming experience, choose the one labeled “Java SE”.

Run the installer.

## TortoiseSVN

Download TortoiseSVN.

Run the installer. More information on svn can be found in this wiki.

After installing TortoiseSVN, right click in Explorer in the empty space in the folder you want to put your project in. Click “SVN checkout” to check out project.

The following example checks out AlgoQuant, a NM Dev powered project. You will use the URL given to you instead. In most cases, you do NOT need to check out AlgoQuant as it will be automatically downloaded by Maven when you build the project.

## Coding in NetBeans

Launch NetBeans. Open your project. You can right click on a package/folder to create a new Java class to start coding. If you are asked to modify the AlgoQuant code, copy and paste the code in your project and do the editing there. Do NOT modify source code in AlgoQuant directly.

To build your project, right click on the project and hit “Clean and Build”. Alternatively, you can hit this button on the top bar.

To run your project, you need to create JUNIT test cases. We run our project by running the test cases. To create a JUNIT test case file, hit “CTRL+SHIRT+U”. This will create a test file for you where you will put your test cases. You can right click on the test file and run it – either in normal or debug mode.

## Debugger

https://netbeans.org/features/java/debugger.html

https://netbeans.org/kb/docs/java/debug-visual.html

## Commit Code

When you are done with coding a milestone, you can submit your code by committing code. Right click the project folder. Select “SVN Commit”.

Type in some meaningful messages to let people know what changes and files you make and add. Click “OK” to commit.

## Curve Fitting & Interpolation

• curve fitting
• least-squares
• online interpolation
• the Neville method
• univariate
• linear
• Newton polynomial
• (natural) cubic spline
• cubic Hermite spline
• bivariate grid
• bilinear
• bicubic
• bicubic spline
• multivariate grid
• multi-linear
• multi-cubic spline
• general recursive grid interpolation

## DSP

This is a collection of the algorithms for digital signal processing.

• Fast Fourier Transform (FFT)

## EVT

This is a collection of algorithms for Extreme Value Theory.

• univariate distributions:
• Gumbel
• Frechet
• Weibull
• Generalized EV (GEVD)
• Generalized Pareto (GPD)
• maxima
• minima
• order statistics
• bivariate distributions:
• asymmetric logic
• asymmetric mixed
• asymmetric negative logistic
• bilogistic
• Coles-Tawn
• Husler-Reiss
• logistic
• negative bilogistic
• negative logistic
• return level and return period
• extremal index estimation
• Ferro-Seegers algorithm
• cluster analysis
• extreme value markov chain
• extreme value time series, i.e., MARMA(p,q) model
• fitting GEVD by maximum likelihood estimation
• fitting GPD by Peaks-over-Threshold (POT) method
• fitting Gumbel type by Average Conditional Exceedance Rate (ACER) method

## Examples

We collect some practical examples that demonstrate the SuanShu features, APIs and modules.

## Excel

It is possible to integrate .NET code with Microsoft Excel. In the following I will show how create an Excel worksheet that uses SuanShu.NET.

To integrate Visual Sudio with .NET, you need Visual Studio 2008 Professional or higher, as well as Microsoft Office 2007 or higher. Please also ensure that during installation of Visual Studio, you have installed the component Visual Studio Tools for Office Runtime. In this tutorial we will be using Visual Studio 2010 Professional with C#.

## Examples Project

Instead of following the tutorial below, you can download a project containing the described examples [here http://redmine.numericalmethod.com/projects/public/repository/show/SuanShu.NET]. You may also use this project as a starting point for your own application.

The example project for Excel contains some methods that convert between Excel ranges to Vector and Matrix datatypes in SuanShu. If you are planning of using SuanShu in Excel, it is highly recommended that you look at the examples, to see how this is done.

## Setting Up the Project

First we create a new project. If you have everything set up as in SuanShu/DotNet, you should be able to create a Project from an Excel Workbook template. Also don’t forget to enter an appropriate name for the project below the template selection.

On the next screen, simply click ‘OK’.

Having created a new project, you must first add SuanShu.NET to the References again. To do this, please follow the instructions in the previous section. This time however, the license file should be located in your ‘My Documents’ folder. An explanation of how to change the directory in which SuanShu looks for the license file is given in the Tips and Tricks section.

## The Worksheet

Let’s now create a simple example program to demonstrate some simple ways of interacting with the Excel worksheet. In this example we will solve a system of linear equations (of the form Ax = b).

First we will set up our worksheet to hold the input and output of our function. This can be done by editing the worksheet like you would from Excel. Please add the following labels and example numbers:

[one_half][/one_half]

[one_half_last][/one_half_last]

We also add a button to trigger the computation. Open the toolbox (if it isn’t already open, press CTRL + W, X) and drag a Button onto the worksheet.

The button can be renamed by changing its ‘Text’ property in the ‘Properties’ dialog, which by default is in the bottom right corner of the screen.

A useful feature is to assign fields names, which we can then reference in the cods. This is done by right clicking the cell and selecting ‘Define Name…’. Let’s call the cells beneath ‘x:’, ‘b:’ and ‘A:’ ‘xStart’, ‘bStart’ and ‘AStart’ respectively. To manage defined names, you can use the ‘Name Manager’ in the Formulas tab.

Pressing F7 will now take you to the code view. To return to the designer view, press SHIFT + F7. As you can see, a method stub for the button has already been created for you. Let’s now insert the code that solves the linear equation.

## Coding

To simplify the integration of SuanShu with Excel we provide a file called SuanShuExcel, which has methods to read and write scalars, vectors and matrices from the worksheet. If you have started your project from scratch, you should add the file to your project.

Having done this, we can solve the linear equation using the following simple code.

private void button1_Click(object sender, EventArgs e) {
// Read b and A starting at the previously named cells bStart and AStart
Vector b = SuanShuExcel.ReadVector(bStart.Row, bStart.Column, this);
Matrix A = SuanShuExcel.ReadMatrix(AStart.Row, AStart.Column, this);

// Precision parameter
double epsilon = 1E-15;

// Solve the linear equation
LinearSystemSolver solver = new LinearSystemSolver(epsilon);
LinearSystemSolver.Solution solution = solver.solve(A);
Vector x = solution.getParticularSolution(b);

// Write the result starting at the previously named cell xStart
SuanShuExcel.WriteVector(x, xStart.Row, xStart.Column, this);
}


If you are unsure about what any of these do, please refer to the XML comments in SuanShuExcel or the documentation below for SuanShu.

## Running the Project

You are now ready to run the project by pressing F5, as you would for a normal Visual Studio project. When reopening the project, please make sure you open the (.sln) Visual Studio solution and not the (.xlsx) worksheet.

After building a ‘Release’ version (see image below) of a solution, it can then be run by opening the worksheet in the bin\Release folder.

## Another Example

Another example (matrix multiplication) can be found in the examples project. It demonstrates how to automatically recompute the result when the worksheet is changed, how to write matrices and how to use the this.Cells and this.Range classes to clear a range of cells.

## Using Used Defined Functions in Excel

Instead of linking a Visual Studio project with an Excel worksheet, you can also define User Defined Functions, which can be used in formulae, much like Excel’s built-in functions. We provide a project that you can use as a starting point to develop your own UDFs. If you want to create a similar project from scratch or are unsure how this project was created, there is a thorough explanation here.

The project is an ‘Automation Add-In’, enabling Excel to call functions on COM objects from cells on the worksheet. There are other ways of defining UDFs via .NET, but this is the officially supported and for our purposes simplest way.

### Class Structure

The interop protocol between .NET and Excel is called Component Object Model (COM). COM only looks at interfaces rather than base classes, so for COM to recognise our methods we first have to perform the following steps:

1. We define an interface containing definitions of our UDFs
2. Both the interface and the class need the ComVisible(true) attribute
3. Furthermore our class needs to have Guid via the Guid attribute (you can generate Guids using the Tools->Create Guid tool in Visual Studio) and have its interface specified via ComDefaultInterface(typeof(_our_interface)). COM doesn’t care whether you implement the interface in the C# sense, but doing so helps ensuring you implement all required methods from the interface.
4. We add code that adds the location of your dll to the registry. This code can just be copied to any new classes as you create them.

If you add a new file to the project you have to remember to do all these things or the UDF will likely not be found in Excel.

### Converting between SuanShu and COM compatible objects

Like for the previous example we provide a class that converts between SuanShu’s Matrix and Vector objects and the objects that are passed by COM. The class can be found in the SuanShuAddin example project as SuanShuAddin.cs.

### Using the UDFs

I will explain how to use our define UDFs by using matrix multiplication as an example.

To build the project and register the Add-In, Visual Studio must be run with Administrator privileges (in Windows Vista or later this is done by right clicking the shortcut and clicking ‘Run as Administrator’). After building the project, we need to load the UDF in Excel. To do so we first open the ‘Add-In Manager’. To do this in Excel 2010, open the options dialog from the file tab and in the Add-Ins section under ‘Manage’ select ‘Excel Add-Ins’ and press Go.

In the Add-Ins window, press ‘Automation’ and in the ‘Automation Servers’ window find the class you want to load, select it and press OK twice. It’s name will be the project name followed by the class name, e.g. SuanShuAddin.SuanShu.

If the add-in does not appear, it may be because Visual Studio Tools for Office is not activated. A simple way to check this is to open the SuanShuExcel (not the add-in) project and see if you can successfully build and run it.

After having done that, you can use the UDFs as follows:

1. Select the range that you want the result to be written to (or the cell if the output is just a single number).
2. In the formulas tab, click ‘Insert Function’.
3. Under ‘Category’, select one of the Add-Ins you just loaded (each interface is a separate Add-In).
4. Select the function you would like to insert and press OK.
5. Select the input arguments.
6. If the output is just a single number, click OK. If it is a vector or matrix, press CTRL+Shift+Enter.

[one_half][/one_half]

[one_half_last][/one_half_last]

### Example Spreadsheet

We have provided an example spreadsheet (addin_example.xlsx) that you can use to check whether the add-in is working correctly. However you will still need to follow the instructions for building and loading the add-in for the formula in the spreadsheet to work.

# Maven

• How do I exclude NM Dev’s dependencies in my own Java project?
• NM Dev depends on some third-party modules:
• akka-2.1.4
• joda-time-2.8.2
• kryo-2.22
• heaps-2.0 (from teneighty.org)

By default, Maven includes these transitive dependencies in the classpath. If you do not want them to be included in the classpath of your project, you may exclude them explicitly by adding an “exclusion” in the dependency section:

<dependencies>
<dependency>
<groupId>com.numericalmethod</groupId>
<artifactId>suanshu</artifactId>
<version>\${suanshu.version}</version>
<exclusions>
<exclusion>
<groupId>com.esotericsoftware.kryo</groupId> <!-- exclude kryo -->
<artifactId>kryo</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>

See this guide for more information.

# Licensing

• Is there a way to have *one* license file shared by multiple machines?
• Yes, one license file can contain multiple MAC addresses so you can deploy/copy the same file to multiple machines.
• Is it possible to have a license that runs on cloud machines?

# Coding

• Why did you choose to have indexes for matrices starting from 1 and not zero as for most structures in java (and c, …)? This complicates the adaptation of code to use NM Dev matrix models and prone to a lot of “+-1” errors in the indexes (for instance when simply iterating over an array *and* a matrix at the same time…)
• Only the computer scientists count from 0. Everyone else on the planet earth, including the mathematicians, counts from 1. One reason for the computer scientists to count from 0 is indexing to an array element by adding an offset to a starting address. Back in the old C generation, suppose we do, double[] arr = new double[10]; , arr is also a reference to an address of a double or an array of doubles. The address of the 2nd element in the array is computed by adding 8 bytes to arr, i.e., arr + (2 – 1)* 8. In other words, the 2nd object is 1 unit (8 bytes) offset from the starting address. Therefore, an array index in C, C++, Java, C# is the number of offsets from a starting address. It is not the index of the object. NM Dev philosophy is to match symbolically the math equations as much as possible. Most math equations count from 1. All matrices and vectors count from 1. We think that this matching is important for code readability and verification against publications. When we compare our code to the papers, we need not mentally compute this +/-1. Otherwise, the code is very prone to errors, especially when there is a lot of indexing in a complex equation. To avoid doing the +/-1 in coding to some extend, I suggest that the users skip using [0], and count from 1. For example,
double[] v1 = new double[]{Double.NaN, 1., 2., 3., 4., 5.};
Vector v2 = new DenseVector(1., 2., 3., 4., 5.);
Vector v3 = new DenseVector(3);
for (int i = 1; i < = v1.length; ++i) {
v3.set(i, v1[i] + v2.get(i));
}


# Misc

## Floating License

For personal use, a user needs a valid license file (namely, numericalmethod.lic) to use NM Dev on a fixed machine. In the case that the machines on which NM Dev is deployed to are not fixed, e.g., cloud virtual machine or site license, floating license provides an alternative solution. This solution is suitable for a group of users working in the same organization in which they share a predetermined number of licenses.

## License Server

A predetermined number of floating licenses are managed by a dedicated license server. Users from any machine can connect to the server to obtain a temporary license for using NM Dev.

To start the license server, in Windows, double-click the file start-floating-license-server.bat (or, run the script start-floating-license-server.sh in Linux). The script file is packaged with the NM Dev distribution (see the file structure below).

suanshu-x.y.z
|   floating.server.conf
|   floating.user.conf
|   start-floating-license-server.bat
|   start-floating-license-server.sh
|   suanshu-x.y.z.jar
|
\---lib

### Configuration

The port number used by the license server is 8080 by default. To change the port number, one can change the value by editing the configuration file floating.server.conf.

PORT = 8080

### License

The license server itself needs a license file floating.server.lic (under the same folder as the nmdev.jar file) to run. Please contact our sales team to get a license file.

### Run at Startup

License server can be configured to start at machine startup by the following steps:

• Windows 7 or earlier versions
1. Create a shortcut of the batch script by right-clicking the file and selecting “Create shortcut”.
2. Click “Start” menu and locate “Startup”.
3. Right-click “Startup” and select “Explore”.
4. Copy and paste the created shortcut into the Startup folder.
• Windows 8 or later versions
1. Create a shortcut of the batch script by right-clicking the file and selecting “Create shortcut”.
2. Press Windows key + R.
3. Type “shell:startup” into the Run dialog, and press Enter.
4. Copy and paste the created shortcut into the Startup folder.
• Mac OS X
1. Click “Apple” menu, and select “System Preferences”.
2. Click “Users & Groups” icon, and click “Login Items”.
3. Click “+” button at the bottom to add the .sh script file in SuanShu folder.
• Linux
1. Edit the file “~/.bash_profile”.
2. Add a line to call “location_of_suanshu_folder/start-floating-license-server.sh” into the file, and save it.

## Floating Users

A floating user with a valid floating numericalmethod.lic can use NM Dev on any machine (as long as it can connect to the license server).

### Configuration

The IP address and the port number of the license server can be configured via the configuration file floating.user.conf.

SERVER_HOST = 127.0.0.1
SERVER_PORT = 8080

Note that the port number configured here must match the one used by the server.

### License

Floating users also need special license file numericalmethod.lic (under the same folder as the nmdev.jar file). Such license file can be replicated to any machine. Please contact our sales team to get a license file.