| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432 | <!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="pdoc 0.5.2" /><title>acceleration API documentation</title><meta name="description" content="Defines the possible routines for computing the gravitational forces in thesimulation …" /><link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css' rel='stylesheet'><link href='https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/8.0.0/sanitize.min.css' rel='stylesheet'><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet"><style>.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}.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:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#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 h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{font-weight:bold}#index h4 + ul{margin-bottom:.6em}#index .two-column{column-count:2}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-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.name small{font-weight:normal}.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{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase;cursor:pointer}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{overflow:visible}.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%}.admonition{padding:.1em .5em}.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:30%}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.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></head><body><main><article id="content"><header><h1 class="title"><code>acceleration</code> module</h1></header><section id="section-intro"><p>Defines the possible routines for computing the gravitational forces in thesimulation.</p><p>All the methods in these file require a position (n, 3) vector, a mass (n, )vector and an optional softening scale float.</p><details class="source"><summary>Source code</summary><pre><code class="python">"""Defines the possible routines for computing the gravitational forces in thesimulation.All the methods in these file require a position (n, 3) vector, a mass (n, )vector and an optional softening scale float."""import ctypesimport numpy.ctypeslib as ctlimport numpy as npfrom numba import jitdef bruteForce(r_vec, mass, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.       Complexity O(n*m) where n is the total number of masses and m is the       number of massive particles.    Parameters:        r_vec (array): list of particles positions.            Shape (n, 3) where n is the number of particles        mass (array): list of particles masses.            Shape (n,)        soft (float): characteristic plummer softening length scale    Returns:        forces (array): list of forces acting on each particle.            Shape (n, 3)    """    # Only calculate forces from massive particles    mask = mass!=0    massMassive = mass[mask]    rMassive_vec = r_vec[mask]    #  x m x 1 matrix (m = number of massive particles) for broadcasting    mass_mat = massMassive.reshape(1, -1, 1)    # Calculate displacements    # r_ten is the direction of the pairwise displacements. Shape (n, m, 3)    # r_mat is the absolute distance of the pairwise displacements. (n, m, 1)    r_ten = rMassive_vec.reshape(1, -1, 3) - r_vec.reshape(-1, 1, 3)    r_mat = np.linalg.norm(r_ten, axis=-1, keepdims=True)    # Avoid division by zeros    # $a = M / (r + \epsilon)^2$, where $\epsilon$ is the softening scale    # r_ten/r_mat gives the direction unit vector    accel = np.divide(r_ten * mass_mat/(r_mat+soft)**2, r_mat,         where=r_ten.astype(bool), out=r_ten) # Reuse memory from r_ten    return accel.sum(axis=1) # Add all forces on each particle@jit(nopython=True) # Numba annotationdef bruteForceNumba(r_vec, mass, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    It is done in the same way as in bruteForce, but this    method is ran through Numba"""    mask = mass!=0    massMassive = mass[mask]    rMassive_vec = r_vec[mask]    mass_mat = massMassive.reshape(1, -1, 1)    r_ten = rMassive_vec.reshape(1, -1, 3) - r_vec.reshape(-1, 1, 3)    # Avoid np.linalg.norm to allow Numba optimizations    r_mat = np.sqrt(r_ten[:,:,0:1]**2 + r_ten[:,:,1:2]**2 + r_ten[:,:,2:3]**2)    r_mat = np.where(r_mat == 0, np.ones_like(r_mat), r_mat)    accel = r_ten/r_mat * mass_mat/(r_mat+soft)**2    return accel.sum(axis=1) # Add all forces in each particle@jit(nopython=True) # Numba annotationdef bruteForceNumbaOptimized(r_vec, mass, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    This is optimized for high performance with Numba. All massive particles    must appear first."""    accel = np.zeros_like(r_vec)     # Use superposition to add all the contributions    n = r_vec.shape[0] # Number of particles    delta = np.zeros((3,)) # Only allocate this once    for i in range(n):        # Only consider pairs with at least one massive particle i        if mass[i] == 0: break        for j in range(i+1, n):            # Explicitely separate components for high performance            # i.e. do not do delta = r_vec[j] - r_vec[i]            # (The effect of this is VERY relevant (x10) and has to do with            # memory reallocation) Numba will vectorize the loops.            for k in range(3): delta[k] = r_vec[j,k] - r_vec[i,k]            r = np.sqrt(delta[0]*delta[0] + delta[1]*delta[1] + delta[2]*delta[2])            tripler = (r+soft)**2 * r                        # Compute acceleration on first particle            mr3inv = mass[i]/(tripler)            # Again, do NOT do accel[j] -= mr3inv * delta            for k in range(3): accel[j,k] -= mr3inv * delta[k]                        # Compute acceleration on second particle            # For pairs with one massless particle, no reaction force            if mass[j] == 0: break            # Otherwise, opposite direction (+)            mr3inv = mass[j]/(tripler)            for k in range(3): accel[i,k] += mr3inv * delta[k]    return accel# C++ interface, load libraryACCLIB = Nonedef loadCPPLib():    """Loads the C++ shared library to the global variable ACCLIB. Must be    called before using the library."""    global ACCLIB    ACCLIB = ctypes.CDLL('cpp/acclib.so')    # Define appropiate types for library functions    doublepp = np.ctypeslib.ndpointer(dtype=np.uintp) # double**    doublep = ctl.ndpointer(np.float64, flags='aligned, c_contiguous')#double*    # Check cpp/acclib.cpp for function signatures    ACCLIB.bruteForceCPP.argtypes = [doublepp, doublep,         ctypes.c_int, ctypes.c_double]    ACCLIB.barnesHutCPP.argtypes = [doublepp, doublep,         ctypes.c_int, ctypes.c_double, ctypes.c_double,         ctypes.c_double, ctypes.c_double, ctypes.c_double]def bruteForceCPP(r_vec, m_vec, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    This is ran in a shared C++ library through Brute Force (pairwise sums)    Massive particles must appear first."""    # Convert array to data required by C++ library    if ACCLIB is None: loadCPPLib() # Singleton pattern    # Change type to be appropiate for calling library    r_vec_c = (r_vec.ctypes.data + np.arange(r_vec.shape[0])         * r_vec.strides[0]).astype(np.uintp)    # Set return type as double*    ACCLIB.bruteForceCPP.restype = np.ctypeslib.ndpointer(dtype=np.float64,         shape=(r_vec.shape[0]*3,))    # Call the C++ function: double* bruteForceCPP    accel =  ACCLIB.bruteForceCPP(r_vec_c, m_vec, r_vec.shape[0], soft)    # Change shape to get the expected Numpy array (n, 3)    accel.shape = (-1, 3)    return acceldef barnesHutCPP(r_vec, m_vec, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    This is ran in a shared C++ library using a BarnesHut tree"""    # Convert array to data required by C++ library    if ACCLIB is None: loadCPPLib() # Singleton pattern    # Change type to be appropiate for calling library    r_vec_c = (r_vec.ctypes.data + np.arange(r_vec.shape[0])         * r_vec.strides[0]).astype(np.uintp)    # Set return type as double*    ACCLIB.barnesHutCPP.restype = np.ctypeslib.ndpointer(dtype=np.float64,         shape=(r_vec.shape[0]*3,))    # Explicitely pass the corner and size of the box for the top node    px, py, pz = np.min(r_vec, axis=0)    size = np.max(np.max(r_vec, axis=0) - np.min(r_vec, axis=0))    # Call the C++ function: double* barnesHutCPP    accel =  ACCLIB.barnesHutCPP(r_vec_c, m_vec, r_vec.shape[0],         size, px, py, pz, soft)    # Change shape to get the expected Numpy array (n, 3)    accel.shape = (-1, 3)    return accel</code></pre></details></section><section></section><section></section><section><h2 class="section-title" id="header-functions">Functions</h2><dl><dt id="acceleration.barnesHutCPP"><code class="name flex"><span>def <span class="ident">barnesHutCPP</span></span>(<span>r_vec, m_vec, soft=0.0)</span></code></dt><dd><section class="desc"><p>Calculates the acceleration generated by a set of masses on themselves.This is ran in a shared C++ library using a BarnesHut tree</p></section><details class="source"><summary>Source code</summary><pre><code class="python">def barnesHutCPP(r_vec, m_vec, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    This is ran in a shared C++ library using a BarnesHut tree"""    # Convert array to data required by C++ library    if ACCLIB is None: loadCPPLib() # Singleton pattern    # Change type to be appropiate for calling library    r_vec_c = (r_vec.ctypes.data + np.arange(r_vec.shape[0])         * r_vec.strides[0]).astype(np.uintp)    # Set return type as double*    ACCLIB.barnesHutCPP.restype = np.ctypeslib.ndpointer(dtype=np.float64,         shape=(r_vec.shape[0]*3,))    # Explicitely pass the corner and size of the box for the top node    px, py, pz = np.min(r_vec, axis=0)    size = np.max(np.max(r_vec, axis=0) - np.min(r_vec, axis=0))    # Call the C++ function: double* barnesHutCPP    accel =  ACCLIB.barnesHutCPP(r_vec_c, m_vec, r_vec.shape[0],         size, px, py, pz, soft)    # Change shape to get the expected Numpy array (n, 3)    accel.shape = (-1, 3)    return accel</code></pre></details></dd><dt id="acceleration.bruteForce"><code class="name flex"><span>def <span class="ident">bruteForce</span></span>(<span>r_vec, mass, soft=0.0)</span></code></dt><dd><section class="desc"><p>Calculates the acceleration generated by a set of masses on themselves.Complexity O(n*m) where n is the total number of masses and m is thenumber of massive particles.</p><h2 id="parameters">Parameters</h2><dl><dt><strong><code>r_vec</code></strong> : <code>array</code></dt><dd>list of particles positions.Shape (n, 3) where n is the number of particles</dd><dt><strong><code>mass</code></strong> : <code>array</code></dt><dd>list of particles masses.Shape (n,)</dd><dt><strong><code>soft</code></strong> : <code>float</code></dt><dd>characteristic plummer softening length scale</dd></dl><h2 id="returns">Returns</h2><dl><dt><strong><code>forces</code></strong> : <code>array</code></dt><dd>list of forces acting on each particle.Shape (n, 3)</dd></dl></section><details class="source"><summary>Source code</summary><pre><code class="python">def bruteForce(r_vec, mass, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.       Complexity O(n*m) where n is the total number of masses and m is the       number of massive particles.    Parameters:        r_vec (array): list of particles positions.            Shape (n, 3) where n is the number of particles        mass (array): list of particles masses.            Shape (n,)        soft (float): characteristic plummer softening length scale    Returns:        forces (array): list of forces acting on each particle.            Shape (n, 3)    """    # Only calculate forces from massive particles    mask = mass!=0    massMassive = mass[mask]    rMassive_vec = r_vec[mask]    #  x m x 1 matrix (m = number of massive particles) for broadcasting    mass_mat = massMassive.reshape(1, -1, 1)    # Calculate displacements    # r_ten is the direction of the pairwise displacements. Shape (n, m, 3)    # r_mat is the absolute distance of the pairwise displacements. (n, m, 1)    r_ten = rMassive_vec.reshape(1, -1, 3) - r_vec.reshape(-1, 1, 3)    r_mat = np.linalg.norm(r_ten, axis=-1, keepdims=True)    # Avoid division by zeros    # $a = M / (r + \epsilon)^2$, where $\epsilon$ is the softening scale    # r_ten/r_mat gives the direction unit vector    accel = np.divide(r_ten * mass_mat/(r_mat+soft)**2, r_mat,         where=r_ten.astype(bool), out=r_ten) # Reuse memory from r_ten    return accel.sum(axis=1) # Add all forces on each particle</code></pre></details></dd><dt id="acceleration.bruteForceCPP"><code class="name flex"><span>def <span class="ident">bruteForceCPP</span></span>(<span>r_vec, m_vec, soft=0.0)</span></code></dt><dd><section class="desc"><p>Calculates the acceleration generated by a set of masses on themselves.This is ran in a shared C++ library through Brute Force (pairwise sums)Massive particles must appear first.</p></section><details class="source"><summary>Source code</summary><pre><code class="python">def bruteForceCPP(r_vec, m_vec, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    This is ran in a shared C++ library through Brute Force (pairwise sums)    Massive particles must appear first."""    # Convert array to data required by C++ library    if ACCLIB is None: loadCPPLib() # Singleton pattern    # Change type to be appropiate for calling library    r_vec_c = (r_vec.ctypes.data + np.arange(r_vec.shape[0])         * r_vec.strides[0]).astype(np.uintp)    # Set return type as double*    ACCLIB.bruteForceCPP.restype = np.ctypeslib.ndpointer(dtype=np.float64,         shape=(r_vec.shape[0]*3,))    # Call the C++ function: double* bruteForceCPP    accel =  ACCLIB.bruteForceCPP(r_vec_c, m_vec, r_vec.shape[0], soft)    # Change shape to get the expected Numpy array (n, 3)    accel.shape = (-1, 3)    return accel</code></pre></details></dd><dt id="acceleration.bruteForceNumba"><code class="name flex"><span>def <span class="ident">bruteForceNumba</span></span>(<span>r_vec, mass, soft=0.0)</span></code></dt><dd><section class="desc"><p>Calculates the acceleration generated by a set of masses on themselves.It is done in the same way as in bruteForce, but thismethod is ran through Numba</p></section><details class="source"><summary>Source code</summary><pre><code class="python">@jit(nopython=True) # Numba annotationdef bruteForceNumba(r_vec, mass, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    It is done in the same way as in bruteForce, but this    method is ran through Numba"""    mask = mass!=0    massMassive = mass[mask]    rMassive_vec = r_vec[mask]    mass_mat = massMassive.reshape(1, -1, 1)    r_ten = rMassive_vec.reshape(1, -1, 3) - r_vec.reshape(-1, 1, 3)    # Avoid np.linalg.norm to allow Numba optimizations    r_mat = np.sqrt(r_ten[:,:,0:1]**2 + r_ten[:,:,1:2]**2 + r_ten[:,:,2:3]**2)    r_mat = np.where(r_mat == 0, np.ones_like(r_mat), r_mat)    accel = r_ten/r_mat * mass_mat/(r_mat+soft)**2    return accel.sum(axis=1) # Add all forces in each particle</code></pre></details></dd><dt id="acceleration.bruteForceNumbaOptimized"><code class="name flex"><span>def <span class="ident">bruteForceNumbaOptimized</span></span>(<span>r_vec, mass, soft=0.0)</span></code></dt><dd><section class="desc"><p>Calculates the acceleration generated by a set of masses on themselves.This is optimized for high performance with Numba. All massive particlesmust appear first.</p></section><details class="source"><summary>Source code</summary><pre><code class="python">@jit(nopython=True) # Numba annotationdef bruteForceNumbaOptimized(r_vec, mass, soft=0.):    """Calculates the acceleration generated by a set of masses on themselves.    This is optimized for high performance with Numba. All massive particles    must appear first."""    accel = np.zeros_like(r_vec)     # Use superposition to add all the contributions    n = r_vec.shape[0] # Number of particles    delta = np.zeros((3,)) # Only allocate this once    for i in range(n):        # Only consider pairs with at least one massive particle i        if mass[i] == 0: break        for j in range(i+1, n):            # Explicitely separate components for high performance            # i.e. do not do delta = r_vec[j] - r_vec[i]            # (The effect of this is VERY relevant (x10) and has to do with            # memory reallocation) Numba will vectorize the loops.            for k in range(3): delta[k] = r_vec[j,k] - r_vec[i,k]            r = np.sqrt(delta[0]*delta[0] + delta[1]*delta[1] + delta[2]*delta[2])            tripler = (r+soft)**2 * r                        # Compute acceleration on first particle            mr3inv = mass[i]/(tripler)            # Again, do NOT do accel[j] -= mr3inv * delta            for k in range(3): accel[j,k] -= mr3inv * delta[k]                        # Compute acceleration on second particle            # For pairs with one massless particle, no reaction force            if mass[j] == 0: break            # Otherwise, opposite direction (+)            mr3inv = mass[j]/(tripler)            for k in range(3): accel[i,k] += mr3inv * delta[k]    return accel</code></pre></details></dd><dt id="acceleration.loadCPPLib"><code class="name flex"><span>def <span class="ident">loadCPPLib</span></span>(<span>)</span></code></dt><dd><section class="desc"><p>Loads the C++ shared library to the global variable ACCLIB. Must becalled before using the library.</p></section><details class="source"><summary>Source code</summary><pre><code class="python">def loadCPPLib():    """Loads the C++ shared library to the global variable ACCLIB. Must be    called before using the library."""    global ACCLIB    ACCLIB = ctypes.CDLL('cpp/acclib.so')    # Define appropiate types for library functions    doublepp = np.ctypeslib.ndpointer(dtype=np.uintp) # double**    doublep = ctl.ndpointer(np.float64, flags='aligned, c_contiguous')#double*    # Check cpp/acclib.cpp for function signatures    ACCLIB.bruteForceCPP.argtypes = [doublepp, doublep,         ctypes.c_int, ctypes.c_double]    ACCLIB.barnesHutCPP.argtypes = [doublepp, doublep,         ctypes.c_int, ctypes.c_double, ctypes.c_double,         ctypes.c_double, ctypes.c_double, ctypes.c_double]</code></pre></details></dd></dl></section><section></section></article><nav id="sidebar"><h1>Index</h1><div class="toc"><ul></ul></div><ul id="index"><li><h3><a href="#header-functions">Functions</a></h3><ul class=""><li><code><a title="acceleration.barnesHutCPP" href="#acceleration.barnesHutCPP">barnesHutCPP</a></code></li><li><code><a title="acceleration.bruteForce" href="#acceleration.bruteForce">bruteForce</a></code></li><li><code><a title="acceleration.bruteForceCPP" href="#acceleration.bruteForceCPP">bruteForceCPP</a></code></li><li><code><a title="acceleration.bruteForceNumba" href="#acceleration.bruteForceNumba">bruteForceNumba</a></code></li><li><code><a title="acceleration.bruteForceNumbaOptimized" href="#acceleration.bruteForceNumbaOptimized">bruteForceNumbaOptimized</a></code></li><li><code><a title="acceleration.loadCPPLib" href="#acceleration.loadCPPLib">loadCPPLib</a></code></li></ul></li></ul></nav></main><footer id="footer"><p>Generated by <a href="https://pdoc3.github.io/pdoc"><cite>pdoc</cite> 0.5.2</a>.</p></footer><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script><script>hljs.initHighlightingOnLoad()</script></body></html>
 |