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.

[pastacode lang=”java” manual=”Matrix%20A1%20%3D%20new%20DenseMatrix(%0A%20%20new%20double%5B%5D%5B%5D%7B%20%2F%2F%20create%20a%20matrix%0A%20%20%20%20%7B1%2C%202%2C%203%7D%2C%0A%20%20%20%20%7B4%2C%205%2C%206%7D%2C%0A%20%20%20%20%7B7%2C%208%2C%209%7D%0A%7D)%3B” message=”Java matrix” highlight=”” provider=”manual”/]

We can print out the Java matrix to check.

[pastacode lang=”java” manual=”System.out.println(A1)%3B” message=”” highlight=”” provider=”manual”/]

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.

Hit “F6” to run.

Vola! You will see this output.

[pastacode lang=”bash” manual=”%5B%2C1%5D%20%5B%2C2%5D%20%5B%2C3%5D%0A%5B1%2C%5D%201.000000%2C%202.000000%2C%203.000000%2C%0A%5B2%2C%5D%204.000000%2C%205.000000%2C%206.000000%2C%0A%5B3%2C%5D%207.000000%2C%208.000000%2C%209.000000%2C” message=”” highlight=”” provider=”manual”/]

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

[pastacode lang=”java” manual=”int%20rank1%20%3D%20MatrixMeasure.rank(A1)%3B%20%2F%2F%20compute%20A1’s%20rank%0ASystem.out.println(rank1)%3B%20%2F%2F%20rank1%20is%202%20implies%20a%20deficient%20matrix” message=”” highlight=”” provider=”manual”/]

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.

[pastacode lang=”java” manual=”A1.set(3%2C%203%2C%2010)%3B%20%2F%2F%20change%20A1%5B3%2C%203%5D%20to%2010″ message=”” highlight=”” provider=”manual”/]

Note that NM Dev counts from 1!

Let’s try again.

[pastacode lang=”java” manual=”rank1%20%3D%20MatrixMeasure.rank(A1)%3B%20%2F%2F%20compute%20modified%20A1’s%20rank%0ASystem.out.println(String.format(%22rank%20for%20the%20modified%20A1%20%3D%20%25d%22%2C%20rank1))%3B” message=”” highlight=”” provider=”manual”/]

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

[pastacode lang=”java” manual=”Matrix%20A2%20%3D%20new%20Inverse(A1)%3B%20%2F%2F%20compute%20A1%20inverse%0ASystem.out.println(A2)%3B” message=”” highlight=”” provider=”manual”/]

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

[pastacode lang=”bash” manual=”3×3%0A%0A%5B%2C1%5D%20%5B%2C2%5D%20%5B%2C3%5D%0A%5B1%2C%5D%20%C2%A0-0.666667%2C%20-1.333333%2C%201.000000%2C%0A%5B2%2C%5D%20%C2%A0-0.666667%2C%203.666667%2C%20-2.000000%2C%0A%5B3%2C%5D%20%C2%A01.000000%2C%20-2.000000%2C%201.000000%2C” message=”” highlight=”” provider=”manual”/]

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

[pastacode lang=”java” manual=”Matrix%20A3%20%3D%20A1.multiply(A2)%3B%20%2F%2F%20A3%20%3D%20A1%20%25*%25%20A2%0A%2F**%20In%20numerical%20computing%2C%20we%20are%20usually%20satisfied%20to%20compare%20equality%20up%20to%20a%20precision.*%2F%0Afinal%20double%20precision%20%3D%201e-14%3B%20%2F%2F%20A3%20and%20the%203×3%20identity%20matrix%20are%20equal%20up%20to%2014%20decimal%20points%0Aif%20(AreMatrices.equal(A3%2C%20new%20DenseMatrix(3%2C%203).ONE()%2C%20precision))%20%7B%20%2F%2F%20compare%20A3%20to%20the%203×3%20identity%20matrix%0ASystem.out.println(%22A2%20is%20indeed%20A1’s%20inverse%22)%3B” message=”” highlight=”” provider=”manual”/]

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

OK. It works.

Let’s try a vector. We do

[pastacode lang=”java” manual=”Vector%20y%20%3D%20new%20DenseVector(new%20double%5B%5D%7B%20%2F%2F%20create%20a%20vector%0A20%2C%2010%2C%204%0A%7D)%3B” message=”” highlight=”” provider=”manual”/]

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

We solve a linear equation of this form.

Ax = y

We need to set up a linear equation solver.

[pastacode lang=”java” manual=”LinearSystemSolver%20solver%20%3D%20new%20LinearSystemSolver(A1)%3B%20%2F%2F%20set%20up%20the%20linear%20equation%20solver%0AVector%20x%20%3D%20solver.solve(y)%3B%20%2F%2F%20solve%20A1%20%25*%25%20x%20%3D%20y%0ASystem.out.println(x)%3B” message=”” highlight=”” provider=”manual”/]

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

x is a vector

[pastacode lang=”bash” manual=”%5B-22.666667%2C%2015.333333%2C%204.000000%5D” message=”” highlight=”” provider=”manual”/]

Happy coding!

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.

• ​NetBeans Debugger- Short Tutorial
• ​YouTube – Using the NetBeans Debugger

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, 4,318 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.

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:

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.

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

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.

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.