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.

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

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.

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.

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

• groovysh.rc
• SVD decomposition

• Riemann integration

SuanShu Scripting in Groovy

We can make Groovy into one all-powerful math computing environment for numerical analysis.

​Groovy is an object-oriented programming language for the Java platform. It is dynamically compiled to Java Virtual Machine bytecode and therefore inter-operates with SuanShu and other Java libraries. Most Java code is also syntactically valid Groovy. Groovy uses a Java-like but simplified syntax. For example, Groovy syntax removes type (dynamic type), semicolons (optional), return keyword (optional). If you already know Java, the learning effort will be minimal. Therefore, Groovy is a popular scripting language for the Java platform.

Setup

This section describes how to set up in Groovy to use SuanShu to do numerical computing.

1. You need a copy of suanshu.jar and a valid SuanShu license. You may download and purchase our products ​here.

2. Download the latest stable version of Groovy from the ​Groovy website, ​here.

3. Run the installer. When choosing the destination folder, please use one that contains no space and special characters. We recommend for example “C:\Groovy\Groovy-1.7.5”.

4.  Configure the environment variables as in the picture below.

5.  Set up the environment variable JAVA_HOME to point to where your JDK is installed. For example, “C:\Program Files (x86)\Java\jdk1.6.0_20”.

6. Create the Groovy ${user.home} folder. The user.home system property is set by your operating system. For example, it can be C:\Users\Haksun Li on Vista, or C:\Document and Settings\Haksun Li on XP. Create the folder “.groovy”. Please note that when you rename on Windows, you need to type “.groovy.” (a “.” at the end) otherwise Windows will complain (a bug?). Then create the “lib” folder in “.groovy”.

7. Setup SuanShu. Copy and paste the SuanShu jar files, e.g., “suanshu.jar” in .groovy/lib. Copy the SuanShu license file “suanshu.lic” into .groovy.

8.  Modify the Groovy shortcuts to start in the .groovy folder. I created two shortcuts on desktop: one for the Groovy shell (groovysh.exe) and another for the Groovy Console (GroovyConsole). The start-in folder is the current/working directory for Groovy. The SuanShu license management will look for the license file in the current directory.

9.  Congratulations! You are now set up with Groovy and ready to go. You can start up the Groovy shell by double clicking on groovysh.exe (or the shortcut you created). Type this to say ‘hi’.

[box type=”shadow”]

println hi

[/box]

10. You may modify the properties on the shell screen by clicking on the Groovy icon at the upper left hand corner. I changed mine to white background and black font.

Tutorials

The best way to learn a language is by imitation and practice. We have prepared some examples to get you started on scripting SuanShu in Groovy. You may want to consult the references below to learn more about Groovy.

import

For those converting from the Matlab/Octave/R/Scilab, the hardest thing to get used to is “import”. To use any Java class in Groovy, we can either type the fully qualified name such as

[box type=”shadow”]

com.numericalmethod.suanshu.matrix.doubles.dense.DenseMatrix

[/box]

We need to do this every time we want to create a DenseMatrix. This is very cumbersome.

Alternatively, we can declare the namespace of DenseMatrix by “importing” them once for all.

[box type=”shadow”]

import com.numericalmethod.suanshu.matrix.doubles.dense.DenseMatrix

[/box]

Or, we can do

[box type=”shadow”]

import com.numericalmethod.suanshu.matrix.doubles.dense.*

[/box]

to import all classes in the package import com.numericalmethod.suanshu.matrix.doubles.dense.

Although the keyword “import” saves some typing, it can get cumbersome if you need to import many classes. The Groovy shell partially solves this problem by letting users to put the most often used imports in the shell startup script, “groovysh.rc”. This file is found in the .groovy folder (or you can create one in the folder).

We recommend the SuanShu users to include these imports. You can simply copy and paste to append them in your groovysh.rc.

References

• ​Groovy
• ​Groovy setup guide
• ​Groovy documentation
• ​Groovy in Action

We do not include the javadoc files in the zipped package because Maven can automatically download it for you (when you need it) from our repository server. In NetBeans, you can also force it to download the javadoc by clicking the “Dependencies > suanshu-2.2.0 > Download Javadoc”:

Or, right click “Dependencies” and choose “Download Javadoc” for downloading the javadoc of ALL dependencies:

A little “J” means the javadoc is available offline. Then, by clicking “View Javadoc”, you can see the downloaded javadoc in your browser offline.

Eclipse also has similar functions:

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.

Tools

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

• Groovy
• Scala?
• Javascript?

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:

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.