Setup Guide

This tutorial is on how to set up the development environment for programming with the SuanShu library (the Java version). In order to use the SuanShu 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 SuanShu. Although you may choose any IDE you like, we recommend Netbeans. You can download it from ​here. If you are an avid programmer, you may want to download the ‘All’ version. For most of us who are mathematicians with little programming experience, the ‘Java SE’ version suffices.

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 (meaning that you press all three keys Ctrl, Shift and F all at the same time). 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 Tools -> Options -> Keymap.

suanshu.jar

To program the SuanShu library, you will need a licensed copy of suanshu.jar (the actual file name depends on the version that you have). It is a compressed file that contains the SuanShu Java classes for numerical computing. This section walks you through how to set up a SuanShu project. You may skip this section if you want to start programming SuanShu right away. This NetBeans project has everything set up. Please read our Basic Trails to get started. If in the future you would like to update the SuanShu library for a newer version, you will need to come back to this section.

Create a SuanShu project

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

In ‘Project Name’, type whatever you like, e.g., HelloSuanShu. In ‘Project Location’, type where you would like to save your project. Click ‘Finish’.

We need to tell this Java project that we will be calling the SuanShu library. To do so, right click on the project name in the Projects window. Click ‘Properties’.

Click ‘Libraries’. Make sure the ‘Compile’ tab is displayed. Click ‘Add JAR/Folder’ and browse to where you save suanshu.jar. Choose suanshu.jar and then hit ‘OK’.

To install the SuanShu javadoc in NetBeans, we need to associate the suanshu.jar with its javadoc. Click ‘Edit’. Browse where you save suanshu.javadoc.zip and hit ‘OK’.

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

        System.out.println("Hello SuanShu");

        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));

Hit Ctrl+Shift+I to fix the necessary imports. Make sure you select these two.

import com.numericalmethod.suanshu.matrix.doubles.operation.Inverse;
import com.numericalmethod.suanshu.matrix.doubles.Matrix;

Hit Alt+Shift+F to beautify your code. The complete source for this example can be found here.

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

Hello SuanShu
3x3
	[,1] [,2] [,3]
[1,] 1.000000, 2.000000, 1.000000,
[2,] 4.000000, 5.000000, 2.000000,
[3,] 7.000000, 8.000000, 1.000000,
3x3
	[,1] [,2] [,3]
[1,] 1.000000, 2.000000, 1.000000,
[2,] 4.000000, 5.000000, 2.000000,
[3,] 7.000000, 8.000000, 1.000000,  * 3x3
	[,1] [,2] [,3]
[1,] -1.833333, 1.000000, -0.166667,
[2,] 1.666667, -1.000000, 0.333333,
[3,] -0.500000, 1.000000, -0.500000,  = 3x3
	[,1] [,2] [,3]
[1,] 1.000000, 0.000000, 0.000000,
[2,] 0.000000, 1.000000, 0.000000,
[3,] 0.000000, 0.000000, 1.000000,  (the identity matrix)

Congratulations!

Javadoc

SuanShu’s javadoc is the complete reference to the SuanShu 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 SuanShu, please consult our tutorials.