Math.NET Numerics
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

294 lines
24 KiB

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Building Math.NET Numerics
</title>
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="author" content="Christoph Ruegg, Marcus Cuda, Jurgen Van Gael">
<link rel="stylesheet" id="theme_link" href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/4.6.0/materia/bootstrap.min.css">
<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.6.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-Piv4xVNRyMGpqkS2by6br4gNJ7DXjqk09RmUpJ8jgGtD7zP9yug3goQfGII0yAns" crossorigin="anonymous"></script>
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML"></script>
<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico">
<link type="text/css" rel="stylesheet" href="https://numerics.mathdotnet.com/content/navbar-fixed-left.css" />
<link type="text/css" rel="stylesheet" href="https://numerics.mathdotnet.com/content/fsdocs-default.css" />
<link type="text/css" rel="stylesheet" href="https://numerics.mathdotnet.com/content/fsdocs-custom.css" />
<script type="text/javascript" src="https://numerics.mathdotnet.com/content/fsdocs-tips.js"></script>
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<!-- BEGIN SEARCH BOX: this adds support for the search box -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/JavaScript-autoComplete/1.0.4/auto-complete.css" />
<!-- END SEARCH BOX: this adds support for the search box -->
</head>
<body>
<nav class="navbar navbar-expand-md navbar-light bg-secondary fixed-left" id="fsdocs-nav">
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarsExampleDefault" aria-controls="navbarsExampleDefault" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse navbar-nav-scroll" id="navbarsExampleDefault">
<a href="https://numerics.mathdotnet.com/"><img id="fsdocs-logo" src="/logo.png" /></a>
<!-- BEGIN SEARCH BOX: this adds support for the search box -->
<div id="header">
<div class="searchbox" id="fsdocs-searchbox">
<label for="search-by">
<i class="fas fa-search"></i>
</label>
<input data-search-input="" id="search-by" type="search" placeholder="Search..." />
<span data-search-clear="">
<i class="fas fa-times"></i>
</span>
</div>
</div>
<!-- END SEARCH BOX: this adds support for the search box -->
<ul class="navbar-nav">
<li class="nav-header">Math.NET Numerics</li>
<li class="nav-item"><a class="nav-link" href="Packages.html">NuGet & Binaries</a></li>
<li class="nav-item"><a class="nav-link" href="ReleaseNotes.html">Release Notes</a></li>
<li class="nav-item"><a class="nav-link" href="https://github.com/mathnet/mathnet-numerics/blob/master/LICENSE.md">MIT License</a></li>
<li class="nav-item"><a class="nav-link" href="Compatibility.html">Platform Support</a></li>
<li class="nav-item"><a class="nav-link" href="https://numerics.mathdotnet.com/api/">Class Reference</a></li>
<li class="nav-item"><a class="nav-link" href="https://github.com/mathnet/mathnet-numerics/issues">Issues & Bugs</a></li>
<li class="nav-item"><a class="nav-link" href="Users.html">Who is using Math.NET?</a></li>
<li class="nav-header">Contributing</li>
<li class="nav-item"><a class="nav-link" href="Contributors.html">Contributors</a></li>
<li class="nav-item"><a class="nav-link" href="Contributing.html">Contributing</a></li>
<li class="nav-item"><a class="nav-link" href="Build.html">Build & Tools</a></li>
<li class="nav-item"><a class="nav-link" href="https://github.com/mathnet/mathnet-numerics/discussions/categories/ideas">Your Ideas</a></li>
<li class="nav-header">Getting Help</li>
<li class="nav-item"><a class="nav-link" href="https://discuss.mathdotnet.com/c/numerics">Discuss</a></li>
<li class="nav-item"><a class="nav-link" href="https://stackoverflow.com/questions/tagged/mathdotnet">Stack Overflow</a></li>
<li class="nav-header">Getting Started</li>
<l class="nav-item"i><a class="nav-link" href="/">Getting started</a></li>
<li class="nav-item"><a class="nav-link" href="Constants.html">Constants</a></li>
<li class="nav-item"><a class="nav-link" href="Matrix.html">Matrices and Vectors</a></li>
<li class="nav-item"><a class="nav-link" href="Euclid.html">Euclid & Number Theory</a></li>
<li class="nav-item">Combinatorics</li>
<li class="nav-header">Evaluation</li>
<li class="nav-item"><a class="nav-link" href="Functions.html">Special Functions</a></li>
<li class="nav-item"><a class="nav-link" href="Integration.html">Integration</a></li>
<li class="nav-header">Statistics/Probability</li>
<li class="nav-item"><a class="nav-link" href="DescriptiveStatistics.html">Descriptive Statistics</a></li>
<li class="nav-item"><a class="nav-link" href="Probability.html">Probability Distributions</a></li>
<li class="nav-header">Generation</li>
<li class="nav-item"><a class="nav-link" href="Generate.html">Generating Data</a></li>
<li class="nav-item"><a class="nav-link" href="Random.html">Random Numbers</a></li>
<li class="nav-header">Solving Equations</li>
<li class="nav-item"><a class="nav-link" href="LinearEquations.html">Linear Equation Systems</a></li>
<li class="nav-header">Optimization</li>
<li class="nav-item"><a class="nav-link" href="Distance.html">Distance Metrics</a></li>
<li class="nav-header">Curve Fitting</li>
<li class="nav-item"><a class="nav-link" href="Regression.html">Regression</a></li>
<li class="nav-header">Native Providers</li>
<li class="nav-item"><a class="nav-link" href="MKL.html">Intel MKL</a></li>
<li class="nav-header">Working Together</li>
<li class="nav-item"><a class="nav-link" href="CSV.html">Delimited Text Files (CSV)</a></li>
<li class="nav-item"><a class="nav-link" href="MatrixMarket.html">NIST MatrixMarket</a></li>
<li class="nav-item"><a class="nav-link" href="MatlabFiles.html">MATLAB</a></li>
<li class="nav-item"><a class="nav-link" href="IFSharpNotebook.html">IF# Notebook</a></li>
</ul>
</div>
</nav>
<div class="container">
<div class="masthead">
<h3 class="muted">
<a href="https://numerics.mathdotnet.com">Math.NET Numerics</a> |
<a href="https://www.mathdotnet.com">Math.NET Project</a> |
<a href="https://github.com/mathnet/mathnet-numerics">GitHub</a>
</h3>
</div>
<hr />
<div class="container" id="fsdocs-content">
<h1><a name="Building-Math-NET-Numerics" class="anchor" href="#Building-Math-NET-Numerics">Building Math.NET Numerics</a></h1>
<p>If you do not want to use the official binaries, or if you like to modify,
debug or contribute, you can compile locally either using Visual Studio or
manually with the build scripts.</p>
<h2><a name="System-Requirements" class="anchor" href="#System-Requirements">System Requirements</a></h2>
<ul>
<li>.NET Core SDK 3.1.1 (<a href="https://dotnet.microsoft.com/download/dotnet-core/3.1">download</a>)</li>
</ul>
<h2><a name="VisualStudio-and-other-IDEs" class="anchor" href="#VisualStudio-and-other-IDEs">VisualStudio and other IDEs</a></h2>
<p>We clearly separate dependency management from the IDE and therefore recommend to
run <code>restore.cmd</code> or <code>restore.sh</code> once after every git checkout in order to restore
the dependencies exactly as defined. Otherwise Visual Studio and other IDEs
may fail to compile or provide correct IntelliSense.</p>
<p>Tests can be run with the usual integrated NUnit test runners or ReSharper.</p>
<h2><a name="Command-Line-Tools" class="anchor" href="#Command-Line-Tools">Command Line Tools</a></h2>
<p>Instead of a compatible IDE you can also build the solutions directly with
the .NET Core SDK build tools. You may need to run <code>restore.cmd</code> or <code>restore.sh</code>
before, once after every git checkout in order to restore the dependencies.</p>
<pre class="fssnip highlighted"><code lang="fsharp"><span class="id">restore</span><span class="pn">.</span><span class="id">cmd</span> <span class="pn">(</span><span class="k">or</span> <span class="pn">.</span><span class="o">/</span><span class="id">restore</span><span class="pn">.</span><span class="id">sh</span><span class="pn">)</span>
<span class="id">dotnet</span> <span class="id">build</span> <span class="id">MathNet</span><span class="pn">.</span><span class="id">Numerics</span><span class="pn">.</span><span class="id">sln</span>
</code></pre>
<h2><a name="FAKE" class="anchor" href="#FAKE">FAKE</a></h2>
<p>The fully automated build including unit tests, documentation and api
reference, NuGet and Zip packages is using <a href="https://fsharp.github.io/FAKE/">FAKE</a>.</p>
<p>FAKE itself is not included in the repository but it will download and bootstrap
itself automatically when build.cmd is run the first time. Note that this step
is <em>not</em> required when using Visual Studio or the .NET Core SDK directly.</p>
<pre class="fssnip highlighted"><code lang="fsharp"><span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="pn">#</span> <span class="id">normal</span> <span class="id">build</span> <span class="k">and</span> <span onmouseout="hideTip(event, 'fs1', 1)" onmouseover="showTip(event, 'fs1', 1)" class="id">unit</span> <span class="id">tests</span><span class="pn">,</span> <span class="k">when</span> <span onmouseout="hideTip(event, 'fs2', 2)" onmouseover="showTip(event, 'fs2', 2)" class="id">using</span> <span class="id">bash</span> <span class="id">shell</span> <span class="id">on</span> <span class="id">Windows</span> <span class="k">or</span> <span class="id">Linux</span><span class="pn">.</span>
<span class="id">build</span><span class="pn">.</span><span class="id">cmd</span> <span class="pn">#</span> <span class="id">normal</span> <span class="id">build</span> <span class="k">and</span> <span onmouseout="hideTip(event, 'fs1', 3)" onmouseover="showTip(event, 'fs1', 3)" class="id">unit</span> <span class="id">tests</span><span class="pn">,</span> <span class="k">when</span> <span onmouseout="hideTip(event, 'fs2', 4)" onmouseover="showTip(event, 'fs2', 4)" class="id">using</span> <span class="id">Windows</span> <span class="id">CMD</span> <span class="id">shell</span><span class="pn">.</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">build</span> <span class="pn">#</span> <span class="id">normal</span> <span class="id">build</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">build</span> <span class="id">strongname</span> <span class="pn">#</span> <span class="id">normal</span> <span class="id">build</span> <span class="k">and</span> <span class="id">also</span> <span class="id">build</span> <span class="id">strong</span><span class="o">-</span><span class="id">named</span> <span class="id">variant</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">test</span> <span class="pn">#</span> <span class="id">normal</span> <span class="id">build</span><span class="pn">,</span> <span class="id">run</span> <span onmouseout="hideTip(event, 'fs1', 5)" onmouseover="showTip(event, 'fs1', 5)" class="id">unit</span> <span class="id">tests</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">test</span> <span class="id">quick</span> <span class="pn">#</span> <span class="id">normal</span> <span class="id">build</span><span class="pn">,</span> <span class="id">run</span> <span onmouseout="hideTip(event, 'fs1', 6)" onmouseover="showTip(event, 'fs1', 6)" class="id">unit</span> <span class="id">tests</span> <span class="id">except</span> <span class="id">long</span> <span class="id">running</span> <span class="id">ones</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">clean</span> <span class="pn">#</span> <span class="id">cleanup</span> <span class="id">build</span> <span class="id">artifacts</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">docs</span> <span class="pn">#</span> <span class="id">generate</span> <span class="id">documentation</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">api</span> <span class="pn">#</span> <span class="id">generate</span> <span class="id">api</span> <span class="id">reference</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">all</span> <span class="pn">#</span> <span class="id">build</span><span class="pn">,</span> <span class="id">test</span><span class="pn">,</span> <span class="id">docs</span><span class="pn">,</span> <span class="id">api</span> <span class="id">reference</span>
</code></pre>
<p>If the build or tests fail claiming that FSharp.Core was not be found, see
<a href="https://fsharp.org/use/windows/">fsharp.org</a> or install the
<a href="https://go.microsoft.com/fwlink/?LinkId=261286">Visual F# 3.0 Tools</a> directly.</p>
<h2><a name="Dependencies" class="anchor" href="#Dependencies">Dependencies</a></h2>
<p>We manage NuGet and other dependencies with <a href="https://fsprojects.github.io/Paket/">Paket</a>.
You do not normally have to do anything with Paket as it is integrated into our
FAKE build tools, unless you want to actively manage the dependencies.</p>
<p><code>.paket/paket.exe restore</code> will restore the packages
to the exact version specified in the <code>paket.lock</code> file,
<code>.paket/paket.exe install</code> will install or migrate packages after you have
made changes to the <code>paket.dependencies</code> file, <code>.paket/paket.exe outdated</code>
will show whether any packages are out of date and <code>.paket/paket.exe update</code>
will update all packages within the defined constraints. Have a look at the Paket
website for more commands and details.</p>
<h2><a name="Documentation" class="anchor" href="#Documentation">Documentation</a></h2>
<p>This website and documentation is automatically generated from of a set of
<a href="https://commonmark.org/">CommonMark</a> structured files in <code>doc/content/</code> using
<a href="https://tpetricek.github.io/FSharp.Formatting/">FSharp.Formatting</a>.
The final documentation can be built by calling <code>build.sh docs</code>.</p>
<p>However, for editing and previewing the docs on your local machine it is more
convenient to run <code>build.sh DocsWatch</code> in a separate console instead, which
monitors the content files and incrementally regenerates the HTML output
automatically. DocsWatch will also use local/relative URIs instead of absolute
ones, so that the links and styles will work as expected locally. This can
also be enabled in a full one-time build with <code>build.sh DocsDev</code> instead
of just <code>Docs</code>.</p>
<h2><a name="Creating-a-Release" class="anchor" href="#Creating-a-Release">Creating a Release</a></h2>
<p>While only maintainers can make official releases published on NuGet and
referred to from the website, you can use the same tools to make your own
releases for your own purposes.</p>
<p>Versioning is controlled by the release notes. Before building a new version,
first add a new release header and change notes on top of the <code>RELEASENOTES.md</code>
document in the root directory. The fake builds pick this up and propagate it
to the assembly info files automatically.</p>
<p>The build can then be launched by calling:</p>
<pre class="fssnip highlighted"><code lang="fsharp"><span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">all</span>
</code></pre>
<p>The build script will print the current version as part of the the header banner,
which is also included in the release notes document in the build artifacts.
Example:</p>
<pre class="fssnip highlighted"><code lang="fsharp"><span class="c">// __ __ _ _ _ _ ______ _______</span>
<span class="c">// | \/ | | | | | | \ | | ____|__ __|</span>
<span class="c">// | \ / | __ _| |_| |__ | \| | |__ | |</span>
<span class="c">// | |\/| |/ _` | __| &#39;_ \ | . ` | __| | |</span>
<span class="c">// | | | | (_| | |_| | | |_| |\ | |____ | |</span>
<span class="c">// |_| |_|\__,_|\__|_| |_(_)_| \_|______| |_|</span>
<span class="c">//</span>
<span class="c">// Math.NET Numerics - https://numerics.mathdotnet.com</span>
<span class="c">// Copyright (c) Math.NET - Open Source MIT/X11 License</span>
<span class="c">//</span>
<span class="c">// Math.NET Numerics v3.5.0</span>
<span class="c">// Math.NET Numerics MKL Provider v1.7.0</span>
<span class="c">// Math.NET Numerics Data Extensions v3.1.0</span>
</code></pre>
<p>The artifacts are then ready in the <code>out/packages</code> directory.</p>
<h2><a name="Extra-Packages" class="anchor" href="#Extra-Packages">Extra Packages</a></h2>
<p>In addition to the core package this repository also include extra packages
like the data extensions. Most build targets are available for
these packages as well, with the following prefixes:</p>
<ul>
<li><code>Data</code> for the Data Extensions</li>
</ul>
<p>Example: <code>build.sh DataBuild</code></p>
<h2><a name="Intel-MKL-on-Windows" class="anchor" href="#Intel-MKL-on-Windows">Intel MKL on Windows</a></h2>
<p>Building the Intel MKL native provider for Windows requires additionally:</p>
<ul>
<li>Either Intel Parallel Studio 2020 or Intel Math Kernel Library 2020 is installed</li>
<li>
Visual Studio 2019, with the following options
<ul>
<li>Desktop development with C++ workload</li>
<li>Windows 10 SDK (10.0.17763.0)</li>
<li>MSVC v142 - VS 2019 C++ x64/x86 build tools</li>
</ul>
</li>
</ul>
<p>The build can then be triggered by calling:</p>
<pre class="fssnip highlighted"><code lang="fsharp"><span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">MklWinBuild</span> <span class="c">// build both 32 and 64 bit variants</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">MklTest</span> <span class="c">// run all tests with the MKL provider enforced</span>
<span class="pn">.</span><span class="o">/</span><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">MklWinAll</span> <span class="c">// build and run tests</span>
</code></pre>
<p>If you run into an error with <code>mkl_link_tool.exe</code> you may need to patch a targets file,
see <a href="https://software.intel.com/en-us/forums/intel-math-kernel-library/topic/851578">MKL 2020.1, VS2019 linking bug </a>.</p>
<p>The build puts the binaries to <code>out/MKL/Windows/x64</code> (and <code>x86</code>), the NuGet package
to <code>out/MKL/NuGet</code> and a Zip archive to <code>out/MKL/Zip</code>. You can directly use the provider from
there by setting <code>Control.NativeProviderPath</code> to the full path pointing to <code>out/MKL/Windows/</code>;
this is also what the unit tests do when you run the <code>MklTest</code> build target.</p>
<h2><a name="Official-Release-Process-Maintainers-only" class="anchor" href="#Official-Release-Process-Maintainers-only">Official Release Process (Maintainers only)</a></h2>
<ul>
<li><p>Update <code>RELEASENOTES.md</code> file with relevant changes, attributed by contributor (if external). Set date.</p></li>
<li><p>Update <code>CONTRIBUTORS.md</code> file (via <code>git shortlog -sn</code>)</p></li>
<li>
<p>Build Release:</p>
<pre class="fssnip highlighted"><code lang="fsharp"><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">all</span> <span class="o">--</span><span class="id">strongname</span>
</code></pre>
</li>
<li>Commit and push release notes and (auto-updated) assembly info files with new "Release: v1.2.3" commit</li>
<li>
<p>Publish Release:</p>
<pre class="fssnip highlighted"><code lang="fsharp"><span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">PublishDocs</span>
<span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">PublishApi</span>
<span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">PublishTag</span>
<span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">PublishArchive</span>
<span class="id">build</span><span class="pn">.</span><span class="id">sh</span> <span class="id">PublishNuGet</span>
</code></pre>
</li>
<li><p>Consider a tweet via <a href="https://twitter.com/MathDotNet">@MathDotNet</a></p></li>
<li>
<p>Update Wikipedia release version and date for the
<a href="https://en.wikipedia.org/wiki/Math.NET_Numerics">Math.NET Numerics</a> and
<a href="https://en.wikipedia.org/wiki/Comparison_of_numerical_analysis_software">Comparison of numerical analysis software</a> articles.</p>
</li>
</ul>
<div class="fsdocs-tip" id="fs1">type unit = Unit<br /><em>&lt;summary&gt;The type &#39;unit&#39;, which has only one value &quot;()&quot;. This value is special and
always uses the representation &#39;null&#39;.&lt;/summary&gt;<br />&lt;category index=&quot;1&quot;&gt;Basic Types&lt;/category&gt;</em></div>
<div class="fsdocs-tip" id="fs2">val using : resource:&#39;T -&gt; action:(&#39;T -&gt; &#39;U) -&gt; &#39;U (requires &#39;T :&gt; System.IDisposable)<br /><em>&lt;summary&gt;Clean up resources associated with the input object after the completion of the given function.
Cleanup occurs even when an exception is raised by the protected
code. &lt;/summary&gt;<br />&lt;param name=&quot;resource&quot;&gt;The resource to be disposed after action is called.&lt;/param&gt;<br />&lt;param name=&quot;action&quot;&gt;The action that accepts the resource.&lt;/param&gt;<br />&lt;returns&gt;The resulting value.&lt;/returns&gt;</em></div>
</div>
<!-- BEGIN SEARCH BOX: this adds support for the search box -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/JavaScript-autoComplete/1.0.4/auto-complete.css" />
<script type="text/javascript">var fsdocs_search_baseurl = 'https://numerics.mathdotnet.com/';</script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/lunr.js/2.3.8/lunr.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/JavaScript-autoComplete/1.0.4/auto-complete.min.js"></script>
<script type="text/javascript" src="https://numerics.mathdotnet.com/content/fsdocs-search.js"></script>
<!-- END SEARCH BOX: this adds support for the search box -->
</div>
</body>
</html>