|
| 1 | +<!DOCTYPE html> |
| 2 | +<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Multiple Systems · FastMultipole.jl</title><meta name="title" content="Multiple Systems · FastMultipole.jl"/><meta property="og:title" content="Multiple Systems · FastMultipole.jl"/><meta property="twitter:title" content="Multiple Systems · FastMultipole.jl"/><meta name="description" content="Documentation for FastMultipole.jl."/><meta property="og:description" content="Documentation for FastMultipole.jl."/><meta property="twitter:description" content="Documentation for FastMultipole.jl."/><meta property="og:url" content="https://flow.byu.edu/FastMultipole.jl/advanced_usage/"/><meta property="twitter:url" content="https://flow.byu.edu/FastMultipole.jl/advanced_usage/"/><link rel="canonical" href="https://flow.byu.edu/FastMultipole.jl/advanced_usage/"/><script data-outdated-warner src="../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../search_index.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-mocha.css" data-theme-name="catppuccin-mocha"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-macchiato.css" data-theme-name="catppuccin-macchiato"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-frappe.css" data-theme-name="catppuccin-frappe"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-latte.css" data-theme-name="catppuccin-latte"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../">FastMultipole.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../">Introduction</a></li><li><a class="tocitem" href="../quickstart/">Quick Start</a></li><li><a class="tocitem" href="../guided_examples/">Gravitational Example</a></li><li><a class="tocitem" href="../vortex_filament/">Vortex Filament Example</a></li><li><a class="tocitem" href="../tuning/">Tuning Parameters</a></li><li class="is-active"><a class="tocitem" href>Multiple Systems</a><ul class="internal"><li><a class="tocitem" href="#Simultaneous-Computation-of-Several-Target-and-Source-Systems"><span>Simultaneous Computation of Several Target and Source Systems</span></a></li></ul></li><li><a class="tocitem" href="../advanced_usage_2/">Automated Tuning</a></li><li><a class="tocitem" href="../reference/">Reference</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Multiple Systems</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Multiple Systems</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/byuflowlab/FastMultipole.jl" title="View the repository on GitHub"><span class="docs-icon fa-brands"></span><span class="docs-label is-hidden-touch">GitHub</span></a><a class="docs-navbar-link" href="https://github.com/byuflowlab/FastMultipole.jl/blob/main/docs/src/advanced_usage.md" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Multiple-Systems"><a class="docs-heading-anchor" href="#Multiple-Systems">Multiple Systems</a><a id="Multiple-Systems-1"></a><a class="docs-heading-anchor-permalink" href="#Multiple-Systems" title="Permalink"></a></h1><p>The most advanced features of <code>FastMultipole</code> include:</p><ul><li>the ability to solve the <span>$n$</span>-body problem for multiple systems simultaneously in a single FMM call</li><li>satisfy an error tolerance by dynamically adjusting the expansion order of multipole-to-local transformations</li><li>predict the full array of FMM tuning parameters such that an error tolerance is met</li></ul><p>In the this section, and continuing in <a href="../advanced_usage_2/">Automated Tuning</a>, we will first describe how to run the FMM for multi-system problems. Then, we will describe how to impose an error tolerance. Finally, we will show how to automatically tune the FMM parameters.</p><h2 id="Simultaneous-Computation-of-Several-Target-and-Source-Systems"><a class="docs-heading-anchor" href="#Simultaneous-Computation-of-Several-Target-and-Source-Systems">Simultaneous Computation of Several Target and Source Systems</a><a id="Simultaneous-Computation-of-Several-Target-and-Source-Systems-1"></a><a class="docs-heading-anchor-permalink" href="#Simultaneous-Computation-of-Several-Target-and-Source-Systems" title="Permalink"></a></h2><p><code>FastMutipole</code> allows FMM to be performed efficiently on distinct target and source systems. This is done by creating two octrees: one for sources, and one for targets [<a href="../theory/#yokota2013fmm2">3</a>]. For example, say we desire to know the influence of one system of point masses on another, but not vice versa. This is done by passing both systems to the <code>fmm!</code> function with the target system first, as:</p><pre><code class="language-julia hljs">using FastMultipole |
| 3 | +using Random # needed for `gravitational.jl` |
| 4 | + |
| 5 | +gravitational_path = normpath(joinpath(splitdir(pathof(FastMultipole))[1], "..", "test", "gravitational.jl")) |
| 6 | +include(gravitational_path) |
| 7 | + |
| 8 | +target_system = generate_gravitational(123, 1000) |
| 9 | +source_system = generate_gravitational(321, 1000) |
| 10 | + |
| 11 | +fmm!(target_system, source_system) |
| 12 | +println("gravitational acceleration: ", target_system.potential[5:7,1:10], "...")</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">gravitational acceleration: [0.08493884822133471 -0.11084374528095761 0.041347632985565604 -0.1863622292822684 -0.08011810805054259 0.04306673245903066 0.0026037448998806746 0.03587428613837394 -0.08002640294442173 0.15009451094982013; 0.002073840920276872 0.32159304704241165 -0.03967273201136324 -0.005960667742001489 0.03828114050071747 0.14489807182906364 0.010013929319383668 0.05641013581893285 0.021727973779433876 0.0076810843882351145; 0.023957945365164404 -0.09630609717111542 -0.025023566343257052 0.13371455312852643 -0.04538444503621948 -0.07362887885237299 0.08060484661663683 -0.015529897358683232 -0.015618344404806379 0.10559335815763889]...</code></pre><div class="admonition is-success" id="Tip-b200cdf2474cf504"><header class="admonition-header">Tip<a class="admonition-anchor" href="#Tip-b200cdf2474cf504" title="Permalink"></a></header><div class="admonition-body"><p>The <code>fmm!</code> function can take any number of target and source systems, so long as they are passed as tuples. This allows for the simultaneous evaluation of multiple source systems on multiple target systems.</p></div></div><p>In practice, the source system might be a collection of systems, composed of a variety of datastructures. So long as the interface functions are defined for each system, we can pass a tuple of any number of systems as the source and or target. For example, we could evaluate the influence of a system of point masses, point vortices, and vortex filaments on two different target systems:</p><pre><code class="language-julia hljs">using LinearAlgebra |
| 13 | + |
| 14 | +# include vortex filament and particle models and interface functions |
| 15 | +vortex_path = normpath(joinpath(splitdir(pathof(FastMultipole))[1], "..", "test", "vortex.jl")) |
| 16 | +include(vortex_path) |
| 17 | +filament_path = normpath(joinpath(splitdir(pathof(FastMultipole))[1], "..", "test", "vortex_filament.jl")) |
| 18 | +include(filament_path) |
| 19 | + |
| 20 | +# generate systems |
| 21 | +n_bodies = 2000 |
| 22 | +target_one = generate_gravitational(123, n_bodies) |
| 23 | +target_two = generate_vortex(124, n_bodies) |
| 24 | +source_one = generate_gravitational(125, n_bodies) |
| 25 | +source_two = generate_vortex(126, n_bodies) |
| 26 | +source_three = generate_filament_field(n_bodies, n_bodies^0.333, 127; strength_scale=1/n_bodies) |
| 27 | + |
| 28 | +# run FMM |
| 29 | +fmm!((target_one, target_two), (source_one, source_two, source_three); |
| 30 | + scalar_potential=false, gradient=true, hessian=(false, true)) |
| 31 | + |
| 32 | +v1 = target_one.potential[5:7,:] |
| 33 | +v2 = target_two.gradient_stretching[1:3,:] |
| 34 | + |
| 35 | +# run direct |
| 36 | +target_one.potential .= 0.0 |
| 37 | +target_two.potential .= 0.0 |
| 38 | +target_two.gradient_stretching .= 0.0 |
| 39 | +direct!((target_one, target_two), (source_one, source_two, source_three); scalar_potential=false, gradient=true, hessian=(false, true)) |
| 40 | + |
| 41 | +# test accuracy |
| 42 | +println("max error in target one: ", maximum(abs.(target_one.potential[5:7,:] .- v1))) |
| 43 | +println("max error in target two: ", maximum(abs.(target_two.gradient_stretching[1:3,:] .- v2)))</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">max error in target one: 1.4007503612439853e-5 |
| 44 | +max error in target two: 1.0289615966441179e-5</code></pre><p>Note that <code>scalar_potential</code>, <code>gradient</code>, and <code>hessian</code> can be passed as a single boolean or as a tuple of booleans, one for each target system. This allows the user to specify which values are desired for each target system, and avoids unnecessary calculations for values that are not needed. In this case, we have set <code>scalar_potential=false</code> and <code>gradient=true</code> to indicate all target systems, but a tuple <code>hessian=(false,true)</code> to indicate different settings for each. It is worth remembering that these switches must be implemented by the user when overloading the <code>direct!</code> function for each system to act as a source.</p><div class="admonition is-success" id="Tip-39caa8a77e0973de"><header class="admonition-header">Tip<a class="admonition-anchor" href="#Tip-39caa8a77e0973de" title="Permalink"></a></header><div class="admonition-body"><p>The <code>fmm!</code> keyword arguments <code>scalar_potential</code>, <code>gradient</code>, and <code>hessian</code> can be passed as a single boolean or as a tuple of booleans, one for each target system. This allows the user to specify which values are desired for each target system, and avoids unnecessary calculations for values that are not needed.</p></div></div></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../tuning/">« Tuning Parameters</a><a class="docs-footer-nextpage" href="../advanced_usage_2/">Automated Tuning »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.14.1 on <span class="colophon-date" title="Friday 5 September 2025 19:01">Friday 5 September 2025</span>. Using Julia version 1.11.6.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html> |
0 commit comments