We provide a version of SuanShu that can be used in Microsoft .NET environment. The following explains how to set up Visual Studio to use SuanShu.NET.

Please note that SuanShu is primarily a Java library, of which the .NET version is a conversion. Hence there are some benefits gained by using the Java version, which will be described at the bottom of this page.

Obtaining the Distribution

You can download the most recent version of the distribution from SuanShu’s ​product website.

Included in the distribution are:

• The converted suanshu.dll
• A converted version of the JodaTime jar
• The parts of IKVM required to use the converted assemblies.

Importing the Assemblies

In order to use SuanShu.NET in your application, you will need to add it and its dependencies as references in Visual Studio. All of the files that you need to add are included in the distribution.

Visual Studio 2010

These directions are for Visual Studio 2010, although the procedure is very similar for other recent versions.

To add the references, right-click your project in the ‘Solution Explorer’ and click ‘Add Reference’.

[one_half][/one_half]

[one_half_last][/one_half_last]

Alternatively you can also select ‘Add Reference’ from the ‘Project’ menu. This should open the ‘Add Reference’ dialog. In the dialog, please select the ‘Browse’ tab and navigate to the directory in which you downloaded the SuanShu.NET distribution. Select all files and click ‘OK’. You should then see them being listed as References in the ‘Solution Explorer’.

Placing the license file

For SuanShu to run, it has to have access to the license file. In Java it will look for the license file on the classpath of your current project. In .NET it will only check the directory of your executable.

When running your project straight from Visual Studio, this would be the bin\Debug and bin\Release folders inside your project folder. For projects using Office integration features, the license file has to be in your ‘My Documents’ folder. To manually change the license file location, see the tips and tricks section below.

Examples

Using SuanShu with .NET is largely very similar to using it in Java. In the following I will give brief demonstrations on how to do some basic operations in C#.

Simple Example

In the blank project there is a simple example that shows how to call SuanShu code from C# to do matrix multiplication.

After importing the necessary classes (this can be done automatically by Visual Studio):

using com.numericalmethod.suanshu.matrix.doubles;
using com.numericalmethod.suanshu.matrix.doubles.matrixtype.dense;
using com.numericalmethod.suanshu.license;

we can do matrix multiplication with the following code:

Matrix A = new DenseMatrix(new double[][] {
new double[] { 1.0, 2.0, 3.0 },
new double[] { 3.0, 5.0, 6.0 },
new double[] { 7.0, 8.0, 9.0 }
});

Matrix B = new DenseMatrix(new double[][] {
new double[] { 2.0, 0.0, 0.0 },
new double[] { 0.0, 2.0, 0.0 },
new double[] { 0.0, 0.0, 2.0 }
});

Matrix AB = A.multiply(B);
Console.Write(AB.ToString());

Further tips on how to use SuanShu with .NET can be found at the bottom of this page.

Code Examples

https://github.com/nmltd/SuanShu/tree/master/SuanShu.NET

Documentation

Included in the distribution in an XML file containing XML comments, which can be viewed in Visual Studio. However since it is a conversion from Java’s JavaDoc comments, it is possible that documentation for some parts are missing or incomplete. Furthermore documentation for classes from the Java library is not included.

In either of those cases, please check the latest JavaDoc.

Tips and Tricks

Setting the location of the license file

You can manually set the location of the license file before calling any SuanShu code. This can be done by calling:

com.numericalmethod.suanshu.license.License.setLicenseFile()

Datatypes

Since the library uses converted Java datatypes instead of their .NET equivalents. Hence for the SuanShu code to interact with other .NET code you may need to convert the datatypes. For example for lists, this can be accomplished as follows (in C#):

List cSharpList = new List();
java.util.List javaList = java.util.Arrays.asList(cSharpList.ToArray());
List

Unfortunately due to Java’s type erasure at compile time, the converted Java collections are not generic.

Jagged arrays

In .NET we have multi-dimensional arrays ([,] in C#) and jagged arrays ([][], e.g. arrays of arrays). Since Java only supports the latter, functions for which a multi-dimensional array would have been appropriate, will use jagged arrays. To see how a jagged array is defined, see the matrix example above.

Benefits of using the Java version

Even though the .NET version of SuanShu is fully featured, there are a few benefits of using the Java version:

• Performance is about 2x better
• The JavaDoc documentation is more complete than the XML comments
• There is no need to convert between .NET and Java datatypes
• Types are generic
• The naming conventions of SuanShu are consistent with Java conventions

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.

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.