NM Dev

NM Dev is a math library of numerical algorithms. It allows engineers to develop very high quality solutions for mathematical problems very rapidly. You will take less time to produce more elegant, object-oriented code that is better tuned, has fewer bugs and runs faster. NM Dev is an object-oriented, high performance, extensively tested, and professionally documented library of numerical methods. It is a large collection of numerical algorithms so coded such that they are solidly object-oriented, unified and testable. We have been writing numerical code for more than a decade since year 2010. Learning from our a decade of experience coding SuanShu (then popular math library now deprecated), we write NM Dev from scratch to make it even better in all ways.

NM Dev has for each mathematical concept a class, instead of a procedure like our competitors’ products. More importantly, these classes are designed so that they are very easy-to-use and easy-to-integrate. They can be assembled and connected in many ways to construct more complicated concepts, hence new classes. The built-in and user-defined, old and new, simple and complex classes all conform to the same design standard to ensure that they are compatible. NM Dev is to engineering solution as Lego is to toy model. NM Dev’s core technology is the design standard and this collection of classes. The goal is that the user, who has little programming experience or understanding in mathematics, can quickly put together these classes to create a solution for his complex problem. For him to assemble our classes to construct an application is as easy as a child assembles Lego pieces to construct a toy robot. Lego has simple pieces like bricks and gears and complex ones like mini-figures. NM Dev has simple classes like matrix and vector, complex ones like regression, and very sophisticated ones like PDE solvers. Using NM Dev, the user will find solving PDE not more difficult or too different from solving zero for equation.

References

Tutorials

There are a number of ways to use NM Dev.

Programming

NM Dev can be used as a programming library component in a software project. For details please read NM Dev tutorials.

SuanShu.net

SuanShu can be used in the .NET environment such as in a C# project or Excel. For details, please read SuanShu.net

Scripting

SuanShu can be used in a similar manner to Matlab/Octave/R/Scilab for research, data analysis and prototyping. For details please read SuanShu Scripting.

SuanShu on GitHub

Before you can use SuanShu, you must have an IDE installed as well as the Java SE Development Kit (JDK). You can download the latest edition of the JDK here. In this guide we will be using IntelliJ IDEA which can be downloaded here.

To download SuanShu source code, view the GitHub repository here. and click the download code button > “Download ZIP”.

Next go to your downloads folder and click on the ‘SuanShu-master.zip’ file and a new file ‘SuanShu-master’ should appear in your downloads.

Now that we have the source code, we can view it using our IDE. Open IntelliJ IDEA and click “Open”.

Navigate to the ‘SuanShu-master’ file > pom.xml and click “Open” > “Open as project”. Your IntelliJ IDEA window should look like this.

Click on “File” > “Project Structure”

and ensure that your project SDK is set to your version of the JDK.

Next right click on the ‘src’ folder > “Mark Directory as” > “Sources root”

 

Then right click the ‘src’ > ‘main’ > ‘java’ > ‘com.numericalmethod.suanshu’ folder and click “New” > “Java Class”. name this class “Main”.

 

Create a main method and you are ready to use any of the classes in the SuanShu library!

Here are some example uses of SuanShu.

If you wanted to work with vectors, you could write

Vector v1 = new DenseVector(new double[]{1, 2, 3, 4, 5});
Vector v2 = v1.scaled(2.0);
System.out.print(v2);

hover over the red text and press option+return to see the available import options, then select the class you wish to import from and press return

You will see that the import statements have been added in automatically.

Now we can run our code by pressing the green play button (at line 7 in the above picture) and the output is shown at the bottom of the window.

You can find the available methods and syntax for any other operation you want to perform by reading through the file that contains your desired mathematical operations. If you want more examples of the SuanShu library, you can have a look at this page.

NM Dev Setup Guide

Setup Guide

This tutorial is on how to set up the development environment for programming with the NM Dev library (the Java version). In order to use the NM Dev library, you need to know some Java programming. Sun (or Oracle) provides excellent online tutorials on learning Java. You can find a lot of easy-to-read-and-follow lessons in Sun’s Java Tutorials.

IDE

You will need an Integrated Development Environment (IDE) to program NM Dev. Although you may choose any IDE you like, we recommend Netbeans. You can download it from here.

 

To learn about how to use NetBeans, you will find a quick start tutorial here. The most important skill for you to learn is debugging. This is especially true for those who are converting from Matlab and R and are used to printing out values. NetBeans debugger allows you to easily inspect values, place conditional breakpoints, pause and resume your program and much more. A quick Google search gives these articles.

We cannot emphasize enough that it is imperative that you must master using a debugger to make your programming experience productive and enjoyable.

Hotkey is another tool that will increase your programming productivity. My favorite hotkey is Ctrl+Shift+F (or Alt+Shift+f if you are using windows). It makes my code look pretty and neat. A list of hotkeys is found here. You can customize them to your own taste by going to Netbeans -> Preferences -> Keymap (or Tools -> Options -> Keymap for Windows/Linux).

nmdev.jar

To program the NM Dev library, you will need a licensed copy of nmdev.jar (the actual file name depends on the version that you have). It is a compressed file that contains the NM Dev Java classes for numerical computing. To get a copy of the trial license, please email sales@nm.dev.

  nmdev-1.0.0.zip (13.1 MiB, 2,519 hits)

This section walks you through how to set up a NM Dev project. You may skip this section if you want to start programming NM Dev right away using the S2 IDE which comes in-built with NM Dev. Please read our Basic Trails to get started. If in the future you would like to update the NM Dev library for a newer version, you will need to come back to this section.

Create a NM Dev project

To create a NM Dev project in NetBeans, open the NetBeans IDE, click File -> New Project… (Ctrl+Shift+N). In ‘categories’, choose ‘Java with Ant’; in projects, choose ‘Java Application’. Click ‘Next’.

In ‘Project Name’, type whatever you like, e.g., HelloNMDev. In ‘Project Location’, type where you would like to save your project. Make sure the box ‘Use dedicated Folder for Storing Libraries’ is checked.Then click ‘Finish’.

We need to tell this Java project that we will be calling the NM Dev library. To do so, right click on the ‘Libraries’ Folder in the project tab and click ‘Add JAR/Folder’

Browse to where you saved nmdev.jar. Select nmdev.jar and then hit ‘Open’.

 

To install the NM Dev javadoc in NetBeans, we need to associate the nmdev.jar with its javadoc. Right click the nmdev.jar file you just added and select ‘Edit’.

In the popup window, under the ‘javadoc’ section, click ‘Browse’ and select the nmdev-javadoc.jar file. Then click ‘Open’.

Now, you have created an empty NM Dev project. Copy and paste these lines under “// TODO code application logic here“.

 

[box type=”shadow”]

System.out.println(“Hello NM Dev”);

 

Matrix A1 = new DenseMatrix(new double[][]{//create a matrix

{1, 2, 1},

{4, 5, 2},

{7, 8, 1}

});

System.out.println(A1);

 

Matrix B = new Inverse(A1);//compute the inverse of A1

Matrix I = A1.multiply(B);//this should be the identity matrix

System.out.println(String.format(“%s * %s = %s (the identity matrix)”,

A1,

B,

I));

[/box]

Hit Command+Shift+I (or Ctrl+Shift+I on Windows/Linux) to fix the necessary imports. Make sure these statements appear at the top of your program. Else you can input them manually.

[box type=”shadow”]

import dev.nm.algebra.linear.matrix.doubles.Matrix;
import dev.nm.algebra.linear.matrix.doubles.matrixtype.dense.DenseMatrix;
import dev.nm.algebra.linear.matrix.doubles.operation.Inverse;

[/box]

Hit Alt+Shift+F to beautify your code. Your code should look something like this.

 

Before you can run your code you will have to place your license file by doing

[box type=”shadow”]

import dev.nm.misc.license.License;

License.setLicenseFile(new java.io.File(“your license path”));

[/box]

Right click on the project name, e.g., HelloNMDev, and click ‘Run’ (or simply press F6 if you make this project your main project). Voila! You should see this in your output window (Ctrl+4).

Congratulations!

Javadoc

NM Dev’s javadoc is the complete reference to the NM Dev library. You can read it in a browser, e.g., Internet Explorer. You can bring them up dynamically during programming. Each time you press Ctrl+SPACE after the ‘.’ of any object you create, you will see a list of available methods for this object, and the javadoc for the method selected.

To get more information about programming NM Dev, please consult our tutorials.

 

 

S2 IDE

S2 Integrated Development Environment (IDE) is the platform on which all our products run. Not only can it run all the standard Java and Kotlin libraries, it also provides seamless integration with our products. Simply purchase the license for the desired library, activate the license key and it is ready for use with S2. you can view our available products here and try them out here.

We also have products for financial analytics (AlgoQuant) and for market data analysis (SuperCurve).

S2 IDE will also be capable of interfacing with data science libraries such as WEKA, MOA, MEKA, DeepLearning4J, Mahout etc. and act as a platform where users can make use of all these libraries in a homogenous way to study data without having to learn each of the libraries in depth.

Use cases

HelloNMDev

Hello NM Dev

This tutorial walks you through a simple first example on using the NM Dev library. You will need to have a NM Dev project to follow the examples here. For details on how to create or download a NM Dev project, please read the Setup Guide.

We will create some matrices and vectors and do some simple linear algebra. Java is an object-oriented language. So, other than the primitive types, like int and double, all variables are objects, namely, instances of some object definitions called classes. For example, to have a matrix instance, a matrix variable, or simply a matrix, we create an instance of the Matrix class.

Java matrix
Matrix A1 = new DenseMatrix(
  new double[][]{ // create a matrix
    {1, 2, 3},
    {4, 5, 6},
    {7, 8, 9}
});

We can print out the Java matrix to check.

System.out.println(A1);

In NetBeans the short cut for System.out.println is to type “sout” (without the “”) and then hit the “Tab” key.

To fix the imports, hit “Ctrl+Shift+I”. There are multiple choices. Choose com.numericalmethod.suanshu.matrix.doubles.Matrix.

fix_all_imports_matrix

Hit “F6” to run.

Vola! You will see this output.

[,1] [,2] [,3]
[1,] 1.000000, 2.000000, 3.000000,
[2,] 4.000000, 5.000000, 6.000000,
[3,] 7.000000, 8.000000, 9.000000,

Congratulations! You have just successfully created your first matrix using the NM Dev library. We are now ready to do more.

Let’s check whether this matrix has a full rank. We do

int rank1 = MatrixMeasure.rank(A1); // compute A1's rank
System.out.println(rank1); // rank1 is 2 implies a deficient matrix

The MatrixMeasure.rank method computes the numerical rank. For more information, see Compute the numerical rank of a matrix.

Hit “F6” to run.

We see that the rank of A1 is 2 so A1 is a rank deficient matrix. We can make it a full rank matrix by changing one entry.

A1.set(3, 3, 10); // change A1[3, 3] to 10

Note that NM Dev counts from 1!

Let’s try again.

rank1 = MatrixMeasure.rank(A1); // compute modified A1's rank
System.out.println(String.format("rank for the modified A1 = %d", rank1));

OK. A1 is now a full rank matrix. We can now find its inverse.

Matrix A2 = new Inverse(A1); // compute A1 inverse
System.out.println(A2);

Hit “Ctrl+Shift+I” to fix the imports. Hit “F6” to run. Here is the output.

3x3

[,1] [,2] [,3]
[1,]  -0.666667, -1.333333, 1.000000,
[2,]  -0.666667, 3.666667, -2.000000,
[3,]  1.000000, -2.000000, 1.000000,

It looks good. To make sure, we multiply them together.

Matrix A3 = A1.multiply(A2); // A3 = A1 %*% A2
/** In numerical computing, we are usually satisfied to compare equality up to a precision.*/
final double precision = 1e-14; // A3 and the 3x3 identity matrix are equal up to 14 decimal points
if (AreMatrices.equal(A3, new DenseMatrix(3, 3).ONE(), precision)) { // compare A3 to the 3x3 identity matrix
System.out.println("A2 is indeed A1's inverse");

Hit “Ctrl+Shift+I” to fix the imports. Hit “F6” to run.

OK. It works.

Let’s try a vector. We do

Vector y = new DenseVector(new double[]{ // create a vector
20, 10, 4
});

Hit “Ctrl+Shift+I” to fix the imports. There are multiple choices. Choose “com.numericalmethod.suanshu.vector.doubles.Vector”.

fix_all_imports_vector2

We solve a linear equation of this form.

Ax = y

We need to set up a linear equation solver.

LinearSystemSolver solver = new LinearSystemSolver(A1); // set up the linear equation solver
Vector x = solver.solve(y); // solve A1 %*% x = y
System.out.println(x);

Hit “Ctrl+Shift+I” to fix the imports. There are multiple choices. Choose com.numericalmethod.suanshu.matrix.doubles.linearsystem.LinearSystemSolver.

x is a vector

[-22.666667, 15.333333, 4.000000]

The source code can be browsed in our svn repository here.

Tutorials

The NM Dev Tutorials

The NM Dev tutorials are practical guides for those who would like to create mathematics applications using the NM Dev library. They include lessons with many complete and working examples. Groups of related lessons are organized into “trails”.

For the most up-to-date information on using the NM Dev library, please consult the Javadoc. Please check out the NM Forum, the place to discuss the NM Dev library, mathematics and programming. You are also encouraged to post your questions there to get help beyond documents.

Before you start these lessons, please make sure you have set up the development environment properly. You can find the details in the Setup Guide.

Basic Trails

Specialized Trails

 

Packages

NM Dev is a large collection of numerical algorithms covering many topics in mathematics. The following is a summary of our packages. For a complete listing, please refer to the Javadoc.

  • BASIC: basic numerical analysis algorithms
  • OPTIM: advanced optimization algorithms
  • STATS: advanced statistics algorithms
  • O/PDE: ordinary and partial differential equations
  • DSP: digital signal processing
  • EVT: extreme value theory
  • many more……

All our code is well tested. We have thousands of test cases that run daily.

Disclaimer: For each subject/topic heading above, there may or may not be features you expected. You will have to download the trial version to experiment with the library to decide whether it is suitable for your purpose, or whether the features you are looking for are included in the library or a particular version of the library. For example, we have listed “OLS regression” in the feature list, but not all possible mathematics, subjects, or topics related to OLS regression are found in the NM Dev library.

 

Scripting

In a manner similar to using Matlab/Octave/R/Scilab, we may use SuanShu in an interactive or a scripting environment. This is most appropriate for research, data analysis and rapid prototyping. Often using a script language, the numerical problems may be expressed and solved in a reduced number of code lines as compared to using Java. Also, the users can get immediate feedback for each line execution, without having to first finish the whole program.

Here is a screenshot of using SuanShu in Groovy.

groovy_matrix_example

Tools

There are a number of ways to use SuanShu in a scripting environment. We recommend the following.

Advantages

There are a number of advantages to using SuanShu over other mathematics scripting languages such as Matlab/Octave/R/Scilab. In the following comparisons, we are illustrating the pros and cons using R, but the arguments probably carry over to the other mathematics scripting languages.

No Language Pollution

There is no need to learn and use a very specialized and proprietary language. In general, the proliferation (pollution) of languages causes confusion. There are very established programming languages that junior students and professional programmers already know. The most notable examples are Java, C# and C++. They are general enough to solve any computationally feasible problems. It makes no sense to invent a new language just for an application. The consequences of language pollution are:

  1. the users need to learn a new language just to use a new application, hence a barrier of entry; e.g., the R language to use R;
  2. the heterogeneity of languages introduces unnecessary challenges when combining them to build one integrated system; the more the worse;
  3. debugging a variety of languages is difficult;
  4. the hosting applications are almost never written in Matlab/Octave/R/Scilab; we would thus have to pass a large amount of data back and forth between the applications (e.g., in Java) and the data processing code (e.g., R); this is a severe performance issue;
  5. the specialized language has no use outside its environment; e.g., no one uses the R language outside the R computing environment.

Most programmers already know Java (or can convert from C# and C++ very easily). As SuanShu is written entirely in Java, there is no need to learn a new language to use it.

Better Code

The “real” programming languages (e.g., Java, Groovy, Scala) are better designed than the specialized mathematics languages. They are invented by scientists who really understand programming languages. The modern languages support (or shall I say, demand) object-oriented code, inheritance, interface, anonymous class, closure, functional programming, an advanced memory model and management, automatic garbage collection and etc. In contrast, the popular mathematics languages have few, if not none, of these features. For example, the R language is a by-and-large procedural imperative C-like language. (Its object-oriented feature is nothing more like a struct in C. It should not be confused with the real object-oriented support in e.g., Java.) It might be acceptable a few decades ago when computer science was at its dawn but certainly not after modern programming languages have come a long way.

In a nutshell, the users of modern programming languages can write better code, in terms of correctness, readability, easiness to debug (maintainability), modularity (object-oriented).

Let’s illustrate our opinion by numerically evaluating this integral:

$\int_0^1 \! x^2 \, \mathrm{d}x$

In Matlab/Octave/R/Scilab, we typically would write something like this.

n = 10000000
sum = 0
for (x in seq(0, 1, 1/n)) {
	sum = sum + x * x # (*)
}
value = sum / n

This would be a piece of perfectly acceptable code many decades ago when C was the most popular programming language. Judging from the modern software engineering perspective, we make one criticism: the mathematics concepts involved are not modular; they cannot be separated out. All this snippet does is to describe one particular procedure to integrate one particular function. There is no reusable code. For example,

  • if you want to integrate another function, you would need to copy and paste this snippet then modify (*);
  • the integrand cannot be manipulated (as a first class citizen); it cannot be evaluated without making a copy outside the integration for-loop; it cannot be passed to another operation, e.g., differentiation, or another way of doing integration, without copying and pasting the same code.

Here is a modern object-oriented way of doing integration using SuanShu in Groovy. Note that the integration algorithm is now independent of the integrand. The integrator can take different integrands, and the integrand is no longer tied to the integrator. This is not to mention that the code is a lot shorter. One statement is to define a Riemann integrator; another statement is to define the integrand. The two objects are independent.

I = new Riemann();//create an integrator
v = I.integrate(
	['evaluate' : {x -> return x * x}] as UnivariateRealFunction,//integrate the function y = x^2
	0, 1);//limit: [0, 1]

Software Engineering Process

Not only does the modern languages like Java allow the users to produce more elegant code, they also come with a suite of software engineering tools and paradigms to improve the coding experience as well as the quality of end products.

First, the computer science community has escaped from the procedural imperative programming mindset to object-oriented programming. We have designed many modern programming techniques, most notably design patterns for effective programming. However, it is not clear if the legacy mathematics languages support inheritance and interface to the extent that we can code patterns using them.

The modern languages come with tools to ensure code correctness. For example, for each mathematics concept, SuanShu has a corresponding class(es). The JUnit tool allows us to systematically and automatically do regression tests on all the source code regularly and when there are code changes. The same goes true for Groovy, Scala and etc. In contrast, suppose we have 100s of R scripts that depend on each other. When we make code changes in one of them, it is not clear how to systematically and automatically make sure that the changes are correct for this particular R file and that all other scripts will work after the changes. Specifically, suppose we make a fundamental change in the way the coefficients in an ARMA model are estimated, will all other functions that depend on this ARMA fitting still work? Theoretically maybe yes, but practically often no (unless you always write bug free code).

Below is a screenshot of the result of SuanShu unit testing.

junit_example

 

Floating License Server

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.