Upgrading to Version 3

Christoph Ruegg edited this page Jun 21, 2014 · 8 revisions

Math.NET Numerics has grown and matured remarkably since the first release of its second major version (v2). But we also made a few unfortunate design choices over the years, and replaced early functionality with something that works better. We fixed most of these in the third major version, v3. Unfortunately this required a few breaking changes.

If you prefer not to upgrade to v3 just yet, that's fine. If needed we can back-port some bug fixes to the v2 branch. However, we will not add any new features to the old v2 branch and recommend to upgrade if feasible.

Almost all of the breaking changes are quite easy to fix in user code, but they do need to be fixed. We intend to collect common migration steps and tips here on this wiki page; feedback is welcome.

For a list of all the changes, see release notes.

Assemblies & Namespaces

  • No more MathNet.Numerics.IO assembly (see MathNet.Numerics.Data packages instead).
  • No more reference to the zlib package.
  • All the .Algorithms namespaces have been dropped. Fix: remove the Algorithm part.
  • Some of the facade classes like Interpolate have been moved up to the root namespace.
  • The Linear Algebra .Generic namespace was removed. Fix: use the parent namespace MathNet.Numerics.LinearAlgebra instead.

Matrices and Vectors

  • We recommend to always declare matrix and vector variables with the generic root type, e.g. Matrix<double>. You'll never have to cast between different types within the type hierarchy again.
  • There is now a generic way to create matrices and vectors using the builder class. For example, Vector<double>.Build.Random(10) creates a random dense vector of the length 10. Tip: since you often only work with one data type, e.g. doubles, consider declaring var M = Matrix<double>.Build;. Creating a diagonal identity matrix of order 4 then simply becomes M.DiagonalIdentity(4);.
  • There is usually no need to open the type specific namespaces, unless you want to use their static functions to create instances.
  • Use matrix instance methods like QR to create decompositions, instead of constructing them manually.
  • If you use the MKL native provider, consider to use Control.UseNativeMKL() instead of creating a provider instance yourself.


  • Probability distributions are now immutable. If you need to modify a parameter, create a new instance. However, in most cases you actually do not need an instance anymore: all of the distribution classes now provide their distribution functions as well as sampling routines directly as static functions.


  • Tip: The packages now contain a MathNet.Numerics.fsx loader script that adds proper FSI printers for matrices and vectors.
  • Tip: Math.NET Numerics is included in FsLab, in the next version with nice MathJax/LaTeX formatting in FsLab journals.


  • If you use AlmostEqual with numbers-between/ULP semantics, please do review your code to make sure you're still using the expected variant!
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.