Skip to content

Commit 395e7a8

Browse files
islentislent
committed
Update docs, release v0.1.5
1 parent 19eedd8 commit 395e7a8

16 files changed

Lines changed: 875 additions & 59 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
Manifest.toml
22
docs/build
33
temp/
4+
build_log.txt
5+
build_log2.txt

‎Project.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ uuid = "dc5d4990-50a5-4af2-bdaa-6f78dc9b9fb2"
33
license = "GPLv3"
44
authors = ["islent <leoislent@gmail.com>"]
55
repository = "https://github.com/JuliaAstroSim/PhysicalTrees.jl"
6-
version = "0.1.4"
6+
version = "0.1.5"
77

88
[deps]
99
BangBang = "198e06fe-97b7-11e9-32a5-e1d131e6ad66"

‎docs/src/index.md‎

Lines changed: 101 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,111 @@
1+
```@meta
2+
CurrentModule = PhysicalTrees
3+
```
4+
15
# PhysicalTrees.jl
26

3-
*Tools to construct distributed unitful trees*
7+
*Distributed octrees for N-body simulation*
8+
9+
[PhysicalTrees.jl](https://github.com/JuliaAstroSim/PhysicalTrees.jl)
10+
is a package in the [JuliaAstroSim](https://github.com/JuliaAstroSim)
11+
ecosystem. It builds and queries space-partitioning **octrees** over
12+
particle data, in a way that is
13+
14+
* **Unitful** — positions, smoothing lengths and box sizes carry their
15+
physical units (kpc, Myr, M⊙, …) end to end; unit errors are caught
16+
at the call site rather than producing silent nonsense.
17+
* **Distributed** — the build pipeline is split across multiple
18+
workers and the tree is rebuilt in place after data movement.
19+
* **Composable** — sits on top of [PhysicalParticles.jl](https://juliaastrosim.github.io/PhysicalParticles.jl/dev/)
20+
and re-exports its `PVector`, `Star`, `Massless`, `extent` and
21+
`datadimension`, so the rest of the ecosystem is one `using` away.
22+
23+
## Why an octree?
24+
25+
An N-body simulation needs to evaluate gravity (or SPH kernels)
26+
between every pair of nearby particles. A naïve double loop is
27+
``\mathcal O(N^2)``; an octree brings this down to ``\mathcal O(N\log N)``
28+
by only descending into a node when the field it represents could
29+
materially contribute.
30+
31+
## Package Features
32+
33+
- Octree construction from raw `PVector`s, from
34+
`StructArray{<:AbstractParticle}`, and from unitless or unitful
35+
data.
36+
- Multi-worker tree construction via
37+
[`ParallelOperations`](https://github.com/JuliaAstroSim/ParallelOperations.jl).
38+
- Neighbor search:
39+
* [`ngb_treefind_variable`](@ref) / [`ngb_treefind_pairs`](@ref) —
40+
single-center cube / sphere search.
41+
* [`ngb_treefind_all`](@ref) / [`ngb_treefind_pairs_all`](@ref) —
42+
bulk neighbor list for every local particle (SPH density loop).
43+
* [`search_inbox_local`](@ref) / [`search_inradius_local`](@ref) /
44+
[`search_all_parallel`](@ref) — distributed variants that return
45+
per-task export flags so the caller can pull candidates from
46+
remote workers.
47+
- Periodic boundary conditions with a minimum-image convention
48+
(see [`ngb_periodic_diff`](@ref) and
49+
[`check_incube_periodic`](@ref)).
50+
- `update_node_len` — re-enlarges node `SideLength`s after particles
51+
have moved, equivalent to Gadget-2's
52+
`force_update_node_len_local`.
53+
54+
## Quick start
55+
56+
```julia
57+
using PhysicalParticles, PhysicalTrees, Unitful, UnitfulAstro
58+
using Distributed
59+
addprocs(2)
60+
@everywhere using PhysicalParticles, PhysicalTrees, UnitfulAstro
61+
62+
# Six unitful particles in a (-1, 1)³ kpc cube
63+
pos = [PVector( 1.0, 1.0, 1.0, u"kpc"),
64+
PVector(-1.0, -1.0, -1.0, u"kpc"),
65+
PVector( 1.0, 0.0, -1.0, u"kpc"),
66+
PVector(-1.0, 0.0, 1.0, u"kpc"),
67+
PVector( 0.0, 0.0, -1.0, u"kpc"),
68+
PVector(-1.0, 0.0, 0.0, u"kpc")]
469

5-
# Package Features
70+
particles = StructArray(Star(uAstro) for _ in 1:6)
71+
assign_particles(particles, :Pos, pos)
672

7-
- Unitful
8-
- Distributed
9-
- User-friendly interface
73+
# Build the tree across workers 1 and 2
74+
tree = octree(particles, pids = workers())
1075

11-
# Manual Outline
76+
# Find particles inside a unit-radius cube around the origin
77+
ngb = ngb_treefind_variable(PVector(0.0, 0.0, 0.0, u"kpc"), 1.0u"kpc", tree)
78+
79+
# Tear down on all workers when done
80+
unregister(tree)
81+
```
82+
83+
## Manual Outline
1284

1385
```@contents
1486
Pages = [
1587
"manual/guide.md",
88+
"manual/octree.md",
1689
]
17-
```
90+
```
91+
92+
## Library Reference
93+
94+
```@contents
95+
Pages = [
96+
"lib/Types.md",
97+
"lib/Methods.md",
98+
]
99+
```
100+
101+
## Package ecosystem
102+
103+
- Basic data structure: [PhysicalParticles.jl](https://github.com/JuliaAstroSim/PhysicalParticles.jl)
104+
- File I/O: [AstroIO.jl](https://github.com/JuliaAstroSim/AstroIO.jl)
105+
- Initial Condition: [AstroIC.jl](https://github.com/JuliaAstroSim/AstroIC.jl)
106+
- Parallelism: [ParallelOperations.jl](https://github.com/JuliaAstroSim/ParallelOperations.jl)
107+
- Trees: [PhysicalTrees.jl](https://github.com/JuliaAstroSim/PhysicalTrees.jl)
108+
- Meshes: [PhysicalMeshes.jl](https://github.com/JuliaAstroSim/PhysicalMeshes.jl)
109+
- Plotting: [AstroPlot.jl](https://github.com/JuliaAstroSim/AstroPlot.jl)
110+
- [AstroNbodySim.jl](https://github.com/JuliaAstroSim/AstroNbodySim.jl) — gravitational N-body simulations, glue layer, and parallel runtime
111+
- Simulation of wave dark matter: [WaveDM.jl](https://github.com/JuliaAstroSim/WaveDM.jl)

‎docs/src/lib/Methods.md‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,62 @@
11
# Methods
22

3+
```@meta
4+
CurrentModule = PhysicalTrees
5+
```
6+
37
## Index
48

59
```@index
610
Pages = ["Methods.md"]
711
```
812

13+
## Tree construction
14+
915
```@docs
1016
octree
17+
rebuild
18+
unregister
19+
update_node_len
1120
global_extent
12-
```
21+
```
22+
23+
## Parallel operations
24+
25+
```@docs
26+
procs
27+
send_buffer
28+
```
29+
30+
## Peano-Hilbert
31+
32+
```@docs
33+
peanokey
34+
```
35+
36+
## Low-level search predicates
37+
38+
```@docs
39+
check_incube
40+
check_incube_periodic
41+
check_insphere
42+
ngb_periodic_diff
43+
```
44+
45+
## Single-center neighbor search
46+
47+
```@docs
48+
ngb_treefind_variable
49+
ngb_treefind_pairs
50+
ngb_treefind_all
51+
ngb_treefind_pairs_all
52+
```
53+
54+
## Distributed neighbor search
55+
56+
```@docs
57+
search_inbox_local
58+
search_inradius_local
59+
search_all_parallel
60+
ngb_clear_buf
61+
density_evaluate
62+
```

‎docs/src/lib/Types.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,46 @@
11
# Types
22

3+
```@meta
4+
CurrentModule = PhysicalTrees
5+
```
6+
37
## Index
48

59
```@index
610
Pages = ["Types.md"]
711
```
812

13+
## Tree types
14+
15+
```@docs
16+
AbstractTree
17+
AbstractTree2D
18+
AbstractTree3D
19+
AbstractOctree2D
20+
AbstractOctree3D
21+
AbstractOctreeNode
22+
AbstractOctreeNode2D
23+
AbstractOctreeNode3D
24+
```
25+
26+
## Concrete nodes
27+
928
```@docs
29+
OctreeNode
30+
TopNode
31+
DomainNode
32+
ExtNode
33+
```
1034

11-
```
35+
## Octree
36+
37+
```@docs
38+
Octree
39+
OctreeConfig
40+
```
41+
42+
## Config
43+
44+
```@docs
45+
OctreeConfig(NumData)
46+
```

0 commit comments

Comments
 (0)