Merge pull request #190 from leon-vv/develop

Merge develop into main for release v0.9.0
leon-vv · Jan 6, 2025 · 530a520 · 530a520
2 parents a711544 + 6ec1482
commit 530a520
Show file tree

Hide file tree

Showing 63 changed files with 17,998 additions and 2,419 deletions.
diff --git a/.github/workflows/type-checking.yaml b/.github/workflows/type-checking.yaml
@@ -5,9 +5,12 @@ on:
   pull_request:
     branches:
       - main
+      - develop
   push:
     branches:
       - main
+      - develop
+  workflow_dispatch:
 
 jobs:
   type-check:

diff --git a/Makefile b/Makefile
@@ -1,7 +1,7 @@
 
 .PHONY: clean bdist
 
-traceon/backend/traceon_backend.so: traceon/backend/traceon-backend.c
+traceon/backend/traceon_backend.so: traceon/backend/*.c
 	clang -O3 -march=native -shared -fPIC -ffast-math -Wno-extern-initializer ./traceon/backend/traceon-backend.c -o traceon/backend/traceon_backend.so -lm 
 
 clean:

diff --git a/README.md b/README.md
@@ -1,8 +1,25 @@
 # Traceon
+Traceon is a Python library designed for the modeling of electron microscopes.
+
+Traceon features a Boundary Element Method (BEM) solver that computes electrostatic and magnetostatic fields for accurate particle tracing. By relying on the BEM rather than FEM, Traceon offers notable improvements in speed and accuracy compared to most commercial alternatives. It supports both radially symmetric and fully 3D geometries, while leveraging advanced axial field interpolations to greatly speed up the particle tracing.
+
+### Wait, is this commercial?
+
+The core of Traceon is completely free to use and open source, and distributed under the `MPL 2.0` license. The software downloaded when using `pip install traceon` does not include any closed source software. There is a commercial package called `traceon_pro` which builds on the `traceon` package to provide a more capable library.
+
+| Feature | Traceon | Traceon Pro |
+| --- | :---: | :---: |
+| Parametric mesher  | ✅ | ✅|    
+| Plot module | ✅ | ✅ |
+| Radial symmetric solver (electrostatic, magnetostatic) | ✅ | ✅ |
+| Radial symmetric particle tracer | ✅ | ✅ |
+| Radial symmetric axial interpolation (fast tracing) | ✅ | ✅|
+| 3D direct solver (electrostatic, magnetostatic) | | ✅|
+| 3D solver using fast multipole method  | | ✅|
+| 3D particle tracing | | ✅|
+| 3D axial interpolation (fast tracing) | | ✅|
 
-Traceon is a general software package used for numerical electron optics. Its main feature is the implementation of the Boundary Element Method (BEM) to quickly calculate the surface charge distribution. The program supports both radial symmetry and general three-dimensional geometries. Electron tracing can be done very quickly using accurate radial series interpolation in both geometries. The electron trajectories obtained can help determine the aberrations of the optical components under study.
 
-The core of Traceon is completely free to use and open source. There is a commerical upgrade with more capabilities. The source code in this repository is distributed under the `MPL 2.0` license.
 
 ## Documentation
 

diff --git a/docs/docs/v0.9.0/images/einzel lens electron traces.png b/docs/docs/v0.9.0/images/einzel lens electron traces.png
diff --git a/docs/docs/v0.9.0/images/einzel lens potential along axis.png b/docs/docs/v0.9.0/images/einzel lens potential along axis.png
diff --git a/docs/docs/v0.9.0/images/einzel lens.png b/docs/docs/v0.9.0/images/einzel lens.png
diff --git a/docs/docs/v0.9.0/images/einzel_lens_radial.png b/docs/docs/v0.9.0/images/einzel_lens_radial.png
diff --git a/docs/docs/v0.9.0/traceon/einzel-lens.html b/docs/docs/v0.9.0/traceon/einzel-lens.html
diff --git a/docs/docs/v0.9.0/traceon/excitation.html b/docs/docs/v0.9.0/traceon/excitation.html
diff --git a/docs/docs/v0.9.0/traceon/field.html b/docs/docs/v0.9.0/traceon/field.html
diff --git a/docs/docs/v0.9.0/traceon/focus.html b/docs/docs/v0.9.0/traceon/focus.html
@@ -0,0 +1,199 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1">
+  <meta name="generator" content="pdoc3 0.11.5">
+
+
+
+    <title>traceon.focus API documentation</title>
+    <meta name="description" content="Module containing a single function to find the focus of a beam of electron trajecories.">
+
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/13.0.0/sanitize.min.css" integrity="sha512-y1dtMcuvtTMJc1yPgEqF0ZjQbhnc/bFhyvIyVNb9Zk5mIGtqVaAB1Ttl28su8AvFMOY0EwRbAe+HCLqj6W7/KA==" crossorigin>
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/13.0.0/typography.min.css" integrity="sha512-Y1DYSb995BAfxobCkKepB1BqJJTPrOp3zPL74AWFugHHmmdcvO+C48WLrUOlhGMc0QG7AE3f7gmvvcrmX2fDoA==" crossorigin>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css" crossorigin>
+
+
+  <style>:root{--highlight-color:#fe9}.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#content .doc-image{padding:0px;display:block;margin:0px auto}#sidebar{padding:1.5em;padding-left:2.5em;overflow:hidden}#sidebar > *:last-child{margin-bottom:2cm}#sidebar .title{font-weight:bold}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:2em 0 .50em 0}h3{font-size:1.4em;margin:1.6em 0 .7em 0}h4{margin:0;font-size:105%}h1:target,h2:target,h3:target,h4:target,h5:target,h6:target{background:var(--highlight-color);padding:.2em 0}a{color:#058;text-decoration:none;transition:color .2s ease-in-out}a:visited{color:#503}a:hover{color:#b62}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900;font-weight:bold}pre code{font-size:.8em;line-height:1.4em;padding:1em;display:block}code{background:#f3f3f3;font-family:"DejaVu Sans Mono",monospace;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index .selected{background:transparent;font-weight:bold}#index a{color:#058}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{margin-top:.6em;font-weight:bold}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}dt:target .name{background:var(--highlight-color)}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source > summary,.git-link-div{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase}.source summary > *{white-space:nowrap;cursor:pointer}.git-link{color:inherit;margin-left:1em}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible;min-width:max-content}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}td{padding:0 .5em}.admonition{padding:.1em 1em;margin:1em 0}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
+  <style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:29%;min-width:525px;height:100vh;overflow:auto;position:sticky;top:0}#content{width:80%;max-width:110ch;padding:3em 6em;border-left:1px solid #ddd}pre code{font-size:1em}.name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul ul{padding-left:1em}.toc > ul > li{margin-top:.5em}}</style>
+  <style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
+
+
+
+    <script type="text/x-mathjax-config">MathJax.Hub.Config({ tex2jax: { inlineMath: [ ['$','$'], ["\\(","\\)"] ], processEscapes: true } });</script>
+    <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS_CHTML" integrity="sha256-kZafAc6mZvK3W3v1pHOcUix30OHQN6pU/NO2oFkqZVw=" crossorigin></script>
+
+    <script defer src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js" integrity="sha512-D9gUyxqja7hBtkWpPWGt9wfbfaMGVt9gnyCvYa+jojwwPHLCzUm5i8rpk7vD7wNee9bA35eYIjobYPaQuKS1MQ==" crossorigin></script>
+    <script>window.addEventListener('DOMContentLoaded', () => {
+        hljs.configure({languages: ['bash', 'css', 'diff', 'graphql', 'ini', 'javascript', 'json', 'plaintext', 'python', 'python-repl', 'rust', 'shell', 'sql', 'typescript', 'xml', 'yaml']});
+        hljs.highlightAll();
+        /* Collapse source docstrings */
+        setTimeout(() => {
+            [...document.querySelectorAll('.hljs.language-python > .hljs-string')]
+                .filter(el => el.innerHTML.length > 200 && ['"""', "'''"].includes(el.innerHTML.substring(0, 3)))
+                .forEach(el => {
+                    let d = document.createElement('details');
+                    d.classList.add('hljs-string');
+                    d.innerHTML = '<summary>"""</summary>' + el.innerHTML.substring(3);
+                    el.replaceWith(d);
+                });
+        }, 100);
+    })</script>
+
+
+</head>
+<body>
+<main>
+    <article id="content">
+
+
+
+
+
+  <header>
+  <h1 class="title">Module <code>traceon.focus</code></h1>
+  </header>
+
+  <section id="section-intro">
+  <p>Module containing a single function to find the focus of a beam of electron trajecories.</p>
+  </section>
+
+  <section>
+  </section>
+
+  <section>
+  </section>
+
+  <section>
+    <h2 class="section-title" id="header-functions">Functions</h2>
+    <dl>
+
+    <dt id="traceon.focus.focus_position"><code class="name flex">
+
+        <span>def <span class="ident">focus_position</span></span>(<span>positions)</span>
+    </code></dt>
+    <dd>
+
+
+
+      <details class="source">
+        <summary>
+            <span>Expand source code</span>
+        </summary>
+        <pre><code class="python">def focus_position(positions):
+    &#34;&#34;&#34;
+    Find the focus of the given trajectories (which are returned from `traceon.tracing.Tracer.__call__`).
+    The focus is found using a least square method by considering the final positions and velocities of
+    the given trajectories and linearly extending the trajectories backwards.
+
+
+    Parameters
+    ------------
+    positions: iterable of (N,6) np.ndarray float64
+        Trajectories of electrons, as returned by `traceon.tracing.Tracer.__call__`
+
+
+    Returns
+    --------------
+    (3,) np.ndarray of float64, representing the position of the focus
+    &#34;&#34;&#34;
+    assert all(p.shape == (len(p), 6) for p in positions)
+
+    angles_x = np.array([p[-1, 3]/p[-1, 5] for p in positions])
+    angles_y = np.array([p[-1, 4]/p[-1, 5] for p in positions])
+    x, y, z = [np.array([p[-1, i] for p in positions]) for i in [0, 1, 2]]
+
+    N = len(positions)
+    first_column = np.concatenate( (-angles_x, -angles_y) )
+    second_column = np.concatenate( (np.ones(N), np.zeros(N)) )
+    third_column = np.concatenate( (np.zeros(N), np.ones(N)) )
+    right_hand_side = np.concatenate( (x - z*angles_x, y - z*angles_y) )
+
+    (z, x, y) = np.linalg.lstsq(
+        np.array([first_column, second_column, third_column]).T,
+        right_hand_side, rcond=None)[0]
+
+    return np.array([x, y, z])</code></pre>
+      </details>
+
+  <div class="desc"><p>Find the focus of the given trajectories (which are returned from <code><a title="traceon.tracing.Tracer.__call__" href="tracing.html#traceon.tracing.Tracer.__call__">Tracer.__call__()</a></code>).
+The focus is found using a least square method by considering the final positions and velocities of
+the given trajectories and linearly extending the trajectories backwards.</p>
+<h2 id="parameters">Parameters</h2>
+<dl>
+<dt><strong><code>positions</code></strong> :&ensp;<code>iterable</code> of <code>(N,6) np.ndarray float64</code></dt>
+<dd>Trajectories of electrons, as returned by <code><a title="traceon.tracing.Tracer.__call__" href="tracing.html#traceon.tracing.Tracer.__call__">Tracer.__call__()</a></code></dd>
+</dl>
+<h2 id="returns">Returns</h2>
+<p>(3,) np.ndarray of float64, representing the position of the focus</p></div>
+</dd>
+
+    </dl>
+  </section>
+
+  <section>
+  </section>
+
+    </article>
+
+
+  <nav id="sidebar">
+
+
+
+	<h1 class='title'><a href='index.html' style='color:black'>Traceon</a></h1>
+
+    <ul id="index">
+
+	<li><h3><a href="#header-submodules">Examples</a></h3>
+      <ul>
+			<li><code><a href="../traceon/einzel-lens.html">Einzel lens</a></code></li>
+      </ul>
+    </li>
+
+    <li><h3><a href="#header-submodules">Traceon</a></h3>
+      <ul>
+        <li><code ><a title="traceon.excitation" href="excitation.html">traceon.excitation</a></code></li>
+        <li><code ><a title="traceon.field" href="field.html">traceon.field</a></code></li>
+        <li><code class='selected'><a title="traceon.focus" href="#traceon.focus">traceon.focus</a></code></li>
+        <li><code ><a title="traceon.geometry" href="geometry.html">traceon.geometry</a></code></li>
+        <li><code ><a title="traceon.logging" href="logging.html">traceon.logging</a></code></li>
+        <li><code ><a title="traceon.mesher" href="mesher.html">traceon.mesher</a></code></li>
+        <li><code ><a title="traceon.plotting" href="plotting.html">traceon.plotting</a></code></li>
+        <li><code ><a title="traceon.solver" href="solver.html">traceon.solver</a></code></li>
+        <li><code ><a title="traceon.tracing" href="tracing.html">traceon.tracing</a></code></li>
+      </ul>
+    </li>
+
+	<li><h3><a href="#header-submodules">Traceon Pro</a></h3>
+      <ul>
+			<li><code ><a title="traceon_pro.field" href="../traceon_pro/field.html">traceon_pro.field</a></code></li>
+			<li><code ><a title="traceon_pro.solver" href="../traceon_pro/solver.html">traceon_pro.solver</a></code></li>
+      </ul>
+    </li>
+
+
+
+    <li><h3><a href="#header-functions">Functions</a></h3>
+
+
+  <ul class="">
+    <li><code><a title="traceon.focus.focus_position" href="#traceon.focus.focus_position">focus_position</a></code></li>
+  </ul>
+
+    </li>
+
+
+    </ul>
+  </nav>
+
+</main>
+
+<footer id="footer">
+
+    <p>Generated by <a href="https://pdoc3.github.io/pdoc" title="pdoc: Python API documentation generator"><cite>pdoc</cite> 0.11.5</a>.</p>
+</footer>
+
+</body>
+</html>