Particular

https://docs.rs/particular/latest
Admin
Particular is a Rust crate that provides a simple API for simulating N-body gravitational...
Tokens:61,343
Snippets:321
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Test WGPU Setup with Brute Force in Rust

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu

Tests the `setup_wgpu` function by blocking on its execution to get a device and queue. It then initializes `GpuResources` and runs acceleration and orbit stability tests using a `BruteForce` implementation.

```rust
#[cfg(test)]
mod tests {
    use super::super::tests;
    use super::*;

    #[test]
    fn brute_force() {
        let (device, queue) = &pollster::block_on(setup_wgpu());
        let resources = &mut GpuResources::new(MemoryStrategy::Shared(64));
        tests::acceleration_error(BruteForce::new(resources, device, queue), 1e-2);
        tests::circular_orbit_stability(BruteForce::new(resources, device, queue), 100, 1e-2);
    }
}

```

--------------------------------

### Setup WGPU Device and Queue - Rust

Source: https://docs.rs/particular/latest/particular/compute_method/gpu/index

A helper function to obtain default instances of `wgpu::Device` and `wgpu::Queue`. This is essential for interacting with the GPU using the wgpu graphics library.

```rust
pub fn setup_wgpu() -> (wgpu::Device, wgpu::Queue) {
    let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
        backends: wgpu::Backends::PRIMARY,
        dx12_validation: false,
    });
    let adapter = instance
        .request_adapter(&wgpu::RequestAdapterOptions {
            power_preference: wgpu::PowerPreference::default(),
            compatible_surface: None,
            force_fallback_adapter: false,
        })
        .await
        .unwrap();

    let (device, queue) = adapter
        .request_device(
            &wgpu::DeviceDescriptor {
                label: None,
                features: wgpu::Features::empty(),
                limits: wgpu::Limits::default(),
            },
            None,
        )
        .await
        .unwrap();

    (device, queue)
}
```

--------------------------------

### Setup WGPU Device and Queue in Rust

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu

Asynchronously sets up a WGPU device and queue, configuring adapter requests for high performance and specifying push constant limits. This is a fundamental step for any WGPU-based rendering or computation.

```rust
pub async fn setup_wgpu() -> (wgpu::Device, wgpu::Queue) {
    let instance = wgpu::Instance::default();

    let adapter = instance
        .request_adapter(&wgpu::RequestAdapterOptions {
            power_preference: wgpu::PowerPreference::HighPerformance,
            ..Default::default()
        })
        .await
        .unwrap();

    adapter
        .request_device(
            &wgpu::DeviceDescriptor {
                label: None,
                required_features: wgpu::Features::empty() | wgpu::Features::PUSH_CONSTANTS,
                required_limits: wgpu::Limits {
                    max_push_constant_size: 4,
                    ..Default::default()
                },
            },
            None,
        )
        .await
        .unwrap()
}

```

--------------------------------

### Accelerations Trait Usage Example (Rust)

Source: https://docs.rs/particular/latest/src/particular/particle

An incomplete example demonstrating the intended use of the `Accelerations` trait for computing particle accelerations from an iterator.

```rust
pub trait Accelerations: Iterator + Sized
where
    Self::Item: Particle,
{
    fn accelerations(&self, compute_method: impl ComputeMethod<Self::Item>) -> Vec<ParticleVector<Self::Item>> {
        compute_method.compute(self)
    }
}

// Example usage snippet (partial):
// let mut particles = vec![([0.0, 1.0], 1.0), ([0.0, 0.0], 1.0)];
```

--------------------------------

### Custom ComputeMethod Implementation (Rust)

Source: https://docs.rs/particular/latest/index

Demonstrates how to implement a custom `ComputeMethod` trait for specific gravitational force computation needs. This example shows a `MyComputeMethod` that delegates to `BruteForceScalar` to compute accelerations for massless particles within a `ParticleSystem`. It allows for tailored algorithms beyond built-in implementations.

```rust
use particular::math::Vec3;

struct MyComputeMethod;

impl ComputeMethod<ParticleReordered<'_, Vec3, f32>> for MyComputeMethod {
    type Output = Vec<Vec3>;

    #[inline]
    fn compute(&mut self, storage: ParticleReordered<Vec3, f32>) -> Self::Output {
        // Only return the accelerations of the massless particles.
        sequential::BruteForceScalar.compute(ParticleSystem {
            affected: storage.massless(),
            massive: storage.massive(),
        })
    }
}
```

--------------------------------

### Example Implementation of ComputeMethod in Rust

Source: https://docs.rs/particular/latest/particular/compute_method/trait

Demonstrates how to implement the `ComputeMethod` trait for a custom struct `AccelerationCalculator`. This example shows the concrete implementation of the `Output` type and the `compute` method, which calculates acceleration for a slice of `PointMass` objects.

```rust
struct AccelerationCalculator;

impl ComputeMethod<&[PointMass<Vec3, f32>]> for AccelerationCalculator {
    type Output = Vec<Vec3>;
     
    fn compute(&mut self, storage: &[PointMass<Vec3, f32>]) -> Self::Output {
        // ...
    }
}
```

--------------------------------

### Using Particle System Storages for Gravitational Computations (Rust)

Source: https://docs.rs/particular/latest/particular

Illustrates the usage of `ParticleSystem`, `ParticleReordered`, and `ParticleTree` storages for computing gravitational accelerations. This example involves creating a `ParticleTree` from massive particles and then computing accelerations on affected particles using a `BarnesHut` compute method. It requires `particular::math::Vec3` and utilizes the `ParticleSystem` struct.

```rust
use particular::math::Vec3;

let particles = vec![];

// Create a `ParticleOrdered` to split massive and massless particles.
let ordered = ParticleOrdered::from(&*particles);

// Build a `ParticleTree` from the massive particles.
let tree = ParticleTree::from(ordered.massive());

// Do something with the tree.
for (node, data) in std::iter::zip(&tree.get().nodes, &tree.get().data) {
    // ...
}

let bh = &mut sequential::BarnesHut { theta: 0.5 };
// The implementation computes the acceleration exerted on the particles in
// the `affected` slice.
// As such, this only computes the acceleration of the massless particles.
let accelerations = bh.compute(ParticleSystem {
    affected: ordered.massless(),
    massive: &tree,
});
```

--------------------------------

### Using ParticleTree for Gravitational Force Computation in Rust

Source: https://docs.rs/particular/latest/src/particular/lib

This example illustrates the advanced usage of `rs_particular` for gravitational simulations. It involves creating a `ParticleOrdered` storage to separate massive and massless particles, building a `ParticleTree` from massive particles, and then using a `BarnesHut` compute method to calculate accelerations on the massless particles.

```rust
# use particular::prelude::*;
use particular::math::Vec3;

let particles = vec![
    // ...
#   PointMass::new(Vec3::new(-10.0, 0.0, 0.0), 5.0),
#   PointMass::new(Vec3::new(-5.0, 20.0, 0.0), 0.0),
#   PointMass::new(Vec3::new(-50.0, 0.0, 5.0), 0.0),
#   PointMass::new(Vec3::new(10.0, 5.0, 5.0), 10.0),
#   PointMass::new(Vec3::new(0.0, -5.0, 20.0), 0.0),
];

// Create a `ParticleOrdered` to split massive and massless particles.
let ordered = ParticleOrdered::from(&*particles);

// Build a `ParticleTree` from the massive particles.
let tree = ParticleTree::from(ordered.massive());

// Do something with the tree.
for (node, data) in std::iter::zip(&tree.get().nodes, &tree.get().data) {
    // ...
}

let bh = &mut sequential::BarnesHut { theta: 0.5 };
// The implementation computes the acceleration exerted on the particles in
// the `affected` slice.
// As such, this only computes the acceleration of the massless particles.
let accelerations = bh.compute(ParticleSystem {
    affected: ordered.massless(),
    massive: &tree,
});
```
```

--------------------------------

### Rust: Initialize WgpuResources

Source: https://docs.rs/particular/latest/particular/compute_method/gpu_compute/struct

Provides a constructor function `new` for WgpuResources, which takes a wgpu::Device and a MemoryStrategy to set up the necessary GPU resources for computation. This is the initial step before any GPU operations can occur.

```rust
pub fn new(device: &Device, shader_type: MemoryStrategy) -> Self
```

--------------------------------

### Infinity Representation

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Provides the method to get the infinity value for f64x4.

```APIDOC
## GET /f64x4/infinity

### Description
Retrieves the infinity value for the f64x4 type.

### Method
GET

### Endpoint
/f64x4/infinity

### Response
#### Success Response (200)
- **infinity_value** (f64x4) - The representation of infinity for f64x4.

#### Response Example
```json
{
  "infinity_value": [ Infinity, Infinity, Infinity, Infinity ]
}
```
```

--------------------------------

### Create WGPU Compute Pipeline and Resources

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu_compute/mod

Initializes necessary WGPU resources including bind group layouts, storage buffers (affected, massive, accelerations), and the compute pipeline. This is essential for preparing the GPU for compute shaders.

```rust
        let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer { ty: wgpu::BufferBindingType::Storage { read_only: true }, has_dynamic_offset: false, min_binding_size: None },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer { ty: wgpu::BufferBindingType::Storage { read_only: true }, has_dynamic_offset: false, min_binding_size: None },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 2,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer { ty: wgpu::BufferBindingType::Storage { read_only: false }, has_dynamic_offset: false, min_binding_size: None },
                    count: None,
                },
            ],
            label: None,
        });

        let buffer_affected = DynamicBuffer::new(
            device,
            &wgpu::BufferDescriptor {
                label: Some("Affected buffer"),
                usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::STORAGE,
                size: 0,
                mapped_at_creation: false,
            },
        );

        let buffer_massive = DynamicBuffer::new(
            device,
            &wgpu::BufferDescriptor {
                label: Some("Massive buffer"),
                usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::STORAGE,
                size: 0,
                mapped_at_creation: false,
            },
        );

        let buffer_accelerations = DynamicBuffer::new(
            device,
            &wgpu::BufferDescriptor {
                label: Some("Accelerations buffer"),
                usage: wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::STORAGE,
                size: 0,
                mapped_at_creation: false,
            },
        );

        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("Compute layout"),
            bind_group_layouts: &[&bind_group_layout],
            push_constant_ranges: &[wgpu::PushConstantRange {
                stages: wgpu::ShaderStages::COMPUTE,
                range: 0..4,
            }],
        });

        let workgroup_size = shader_type.workgroup_size();

        let compute_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: None,
            source: shader_type.as_shader_source(),
        });

        let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
            label: Some("Compute pipeline"),
            layout: Some(&pipeline_layout),
            module: &compute_shader,
            entry_point: "main",
        });

        WgpuResources {
            bind_group_layout,
            buffer_affected,
            buffer_massive,
            buffer_accelerations,
            pipeline,
            workgroup_size,
        }
    }
```

--------------------------------

### f64x4 Infinity Value

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Provides a method to get the infinity (∞) value for the f64x4 type.

```rust
impl Infinity for f64x4 {
    fn infinity() -> Self;
}
```

--------------------------------

### Get the width of a BoundingBox

Source: https://docs.rs/particular/latest/src/particular/compute_method/tree/partition

Implements the `width` method for `BoundingBox<[S; D]>`. This method returns the size of the bounding box along the first dimension (typically the x-axis).

```rust
impl<const D: usize, S>
BoundingBox<[S; D]> 
where
    S: Copy + Float,
{
    /// Returns the width of the [`BoundingBox`] (x element of the size).
    #[inline]
    pub fn width(&self) -> S {
        self.size()[0]
    }
}
```

--------------------------------

### Create GpuResources Instance in Rust

Source: https://docs.rs/particular/latest/particular/compute_method/gpu/struct

Provides functions to create and initialize `GpuResources` instances. The `new` function creates an instance without immediate initialization, while `init` creates an instance with initialized buffers and pipelines, requiring a wgpu `Device`.

```rust
pub fn new(shader_type: MemoryStrategy) -> Self
// Creates a new `GpuResources` instance.
```

```rust
pub fn init(shader_type: MemoryStrategy, device: &Device) -> Self
// Creates a new `GpuResources` instance with initialised buffers and pipeline.
```

--------------------------------

### Formatting Implementations

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Details on how f64x4 can be formatted using `UpperExp` and `UpperHex` traits.

```APIDOC
## impl UpperExp for f64x4

### Description
Implements the `UpperExp` trait for `f64x4`, enabling formatting in upper exponential notation.

### Method
`fmt`

### Endpoint
N/A (Method implementation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Result<(), Error>** - A result indicating success or failure of the formatting operation.

## impl UpperHex for f64x4

### Description
Implements the `UpperHex` trait for `f64x4`, enabling formatting in upper hexadecimal notation.

### Method
`fmt`

### Endpoint
N/A (Method implementation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Result<(), Error>** - A result indicating success or failure of the formatting operation.
```

--------------------------------

### WgpuResources API

Source: https://docs.rs/particular/latest/particular/compute_method/gpu_compute/struct

Documentation for the WgpuResources struct, which holds all wgpu resources needed for GPU computations.

```APIDOC
## Struct WgpuResources

### Description
All the `wgpu` resources needed to perform the computation of accelerations on the GPU.

### Methods

#### `new(device: &Device, shader_type: MemoryStrategy) -> Self`
Creates a new `WgpuResources` with the given `wgpu::Device`.

- **device** (`&Device`) - The wgpu device.
- **shader_type** (`MemoryStrategy`) - The memory strategy for the shaders.

### Request Example
```json
{
  "device": "<wgpu_device_instance>",
  "shader_type": "<memory_strategy_enum>"
}
```

### Response Example
```json
{
  "instance": "<wgpu_resources_instance>"
}
```

#### `write_particle_data(&mut self, affected: &[PointMass<Vec3, f32>], massive: &[PointMass<Vec3, f32>], device: &Device, queue: &Queue)`
Write the given affected and massive particles to GPU buffers.

- **affected** (`&[PointMass<Vec3, f32>]`) - Slice of affected particles.
- **massive** (`&[PointMass<Vec3, f32>]`) - Slice of massive particles.
- **device** (`&Device`) - The wgpu device.
- **queue** (`&Queue`) - The wgpu queue.

### Request Example
```json
{
  "affected": [
    {"position": [x, y, z], "mass": m},
    ...
  ],
  "massive": [
    {"position": [x, y, z], "mass": m},
    ...
  ],
  "device": "<wgpu_device_instance>",
  "queue": "<wgpu_queue_instance>"
}
```

### Response Example
```json
// No explicit response body, operation modifies GPU buffers.
```

#### `compute(&self, device: &Device, queue: &Queue, softening: f32) -> Vec<Vec3>`
Returns the computed accelerations on the GPU.

- **device** (`&Device`) - The wgpu device.
- **queue** (`&Queue`) - The wgpu queue.
- **softening** (`f32`) - Softening factor for calculations.

### Request Example
```json
{
  "device": "<wgpu_device_instance>",
  "queue": "<wgpu_queue_instance>",
  "softening": 0.001
}
```

### Response Example
```json
{
  "accelerations": [
    [ax, ay, az],
    ...
  ]
}
```
```

--------------------------------

### Get Orthtree Root in Rust

Source: https://docs.rs/particular/latest/particular/compute_method/storage/struct

Provides a method to retrieve the root node of the `Orthtree` stored within the `ParticleTree`. Returns an `Option<NodeID>` representing the root, or `None` if the tree is empty.

```rust
pub const fn root(&self) -> Option<NodeID>
```

--------------------------------

### Compute Method for ParticleReordered in Rust

Source: https://docs.rs/particular/latest/src/particular/compute_method/storage

This Rust code defines a `ComputeMethod` for `ParticleReordered` data. It transforms the reordered particles into a `ParticleSliceSystem` for further processing. This enables computations on particle sets that may have been reordered, for example, after a sorting or partitioning step.

```Rust
impl<V, S, C, O> ComputeMethod<&ParticleReordered<'_, V, S>> for C
where
    O: IntoIterator,
    for<'a> C: ComputeMethod<ParticleSliceSystem<'a, V, S>, Output = O>,
{
    type Output = O;

    #[inline]
    fn compute(&mut self, reordered: &ParticleReordered<V, S>) -> Self::Output {
        self.compute(ParticleSliceSystem {
            affected: reordered.unordered,
            massive: reordered.massive(),
        })
    }
}
```

--------------------------------

### Rust Blanket Implementation: CloneToUninit for T

Source: https://docs.rs/particular/latest/particular/compute_method/tree/enum

Demonstrates the blanket implementation of `CloneToUninit` for types `T` that implement `Clone`. This is an experimental, nightly-only API for performing copy-assignment to uninitialized memory.

```Rust
impl<T> CloneToUninit for T where T: Clone {
    unsafe fn clone_to_uninit(&self, dest: *mut u8) {
        // ... implementation details ...
    }
}
```

--------------------------------

### Calculate Particle Accelerations in Rust

Source: https://docs.rs/particular/latest/src/particular/lib

This snippet demonstrates how to calculate accelerations for a vector of particles. It iterates through the particles, updating their velocities and positions based on computed accelerations. This example assumes the iterated type implements the `Particle` trait.

```rust
#! # let mut bodies = Vec::<Body>::new();
for (acceleration, body) in bodies.iter().accelerations(&mut cm).zip(&mut bodies) {
    body.velocity += Vec3::from(acceleration) * DT;
    body.position += body.velocity * DT;
}
```
```

--------------------------------

### Rust: Tree Constructor Methods

Source: https://docs.rs/particular/latest/particular/compute_method/tree/struct

Provides methods to create new instances of the `Tree` struct. `new()` creates an empty tree, while `with_capacity()` initializes an empty tree with a pre-allocated capacity for its internal vectors, optimizing for performance when the eventual size is known.

```rust
pub fn new() -> Self
```

```rust
pub fn with_capacity(capacity: usize) -> Self
```

--------------------------------

### Core Trait Implementations

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Lists essential trait implementations for f64x4, including Copy, Pod, and StructuralPartialEq.

```APIDOC
## impl Copy for f64x4

### Description
Indicates that `f64x4` implements the `Copy` trait, meaning instances can be duplicated by simple bitwise copy.

## impl Pod for f64x4

### Description
Indicates that `f64x4` implements the `Pod` (Plain Old Data) trait, signifying it has a simple memory layout.

## impl StructuralPartialEq for f64x4

### Description
Indicates that `f64x4` implements `StructuralPartialEq`, allowing for structural equality comparisons.
```

--------------------------------

### WgpuResources for GPU Acceleration in Rust

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu_compute/mod

Bundles all `wgpu` resources required for GPU computation of accelerations for massive particles. This includes bind group layouts, dynamic buffers for particles and accelerations, and the compute pipeline itself. It's initialized with a `wgpu::Device` and a `MemoryStrategy`. Dependencies include `wgpu` and the `DynamicBuffer` struct.

```rust
type PointMass = crate::compute_method::storage::PointMass<Vec3, f32>;

const PARTICLE_SIZE: u64 = std::mem::size_of::<PointMass>() as u64;

/// All the `wgpu` resources needed to perform the computation of accelerations on the GPU.
pub struct WgpuResources {
    bind_group_layout: wgpu::BindGroupLayout,
    buffer_affected: DynamicBuffer,
    buffer_massive: DynamicBuffer,
    buffer_accelerations: DynamicBuffer,
    pipeline: wgpu::ComputePipeline,
    workgroup_size: u32,
}

impl WgpuResources {
    /// Creates a new [`WgpuResources`] with the given [`wgpu::Device`].
    #[inline]
    pub fn new(device: &wgpu::Device, shader_type: MemoryStrategy) -> Self {
        let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Storage { read_only: true },
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Storage { read_only: true },

```

--------------------------------

### Calculate Gravitational Force Between PointMasses in Rust

Source: https://docs.rs/particular/latest/src/particular/lib

This snippet demonstrates calculating the gravitational force between two `PointMass` objects using the `force_scalar` method. It takes into account their positions, masses, and a softening parameter. The example uses `Vec2` for 2D positions.

```rust
# use particular::prelude::*;
use particular::math::Vec2;

let p1 = PointMass::new(Vec2::new(0.0, 1.0), 1.0);
let p2 = PointMass::new(Vec2::new(0.0, 0.0), 1.0);
let softening = 0.0;

assert_eq!(p1.force_scalar::<false>(p2.position, p2.mass, softening), Vec2::new(0.0, -1.0));
```
```

--------------------------------

### Calculate Particle Accelerations (Non-Particle Type) in Rust

Source: https://docs.rs/particular/latest/src/particular/lib

This example shows how to calculate accelerations when the iterated type does not directly implement the `Particle` trait. It maps items to a tuple representing position and mass, allowing the `accelerations` method to be used. The code then updates velocity and position.

```rust
# use particular::prelude::*;
# use ultraviolet::Vec3;
# const DT: f32 = 1.0 / 60.0;
# const G: f32 = 1.0;
# let mut cm = sequential::BruteForceScalar;
# let mut items = vec![
#     (Vec3::zero(), -Vec3::one(), 5.0),
#     (Vec3::zero(), Vec3::zero(), 3.0),
#     (Vec3::zero(), Vec3::one(), 10.0),
# ];
let accelerations = items
    .iter()
    .map(|(_, position, mass)| (*position.as_array(), *mass * G))
    .accelerations(&mut cm);

for (acceleration, (velocity, position, _)) in accelerations.zip(&mut items) {
    *velocity += Vec3::from(acceleration) * DT;
    *position += *velocity * DT;
}
```
```

--------------------------------

### f64x4 Instance Methods

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Provides common mathematical and utility methods for f64x4 vectors.

```APIDOC
## f64x4 Instance Methods

### `new(array: [f64; 4]) -> f64x4`
Creates a new `f64x4` vector from a 4-element array.

### `blend(self, t: f64x4, f: f64x4) -> f64x4`
Blends two `f64x4` vectors based on a third `f64x4` vector (likely a mask).

### `abs(self) -> f64x4`
Calculates the element-wise absolute value.

### `floor(self) -> f64x4`
Calculates the element-wise floor.

### `ceil(self) -> f64x4`
Calculates the element-wise ceiling.

### `fast_max(self, rhs: f64x4) -> f64x4`
Calculates the element-wise maximum of two vectors. Faster but does not guarantee NaN behavior.

### `max(self, rhs: f64x4) -> f64x4`
Calculates the element-wise maximum of two vectors, handling NaNs by preferring the non-NaN value.

### `fast_min(self, rhs: f64x4) -> f64x4`
Calculates the element-wise minimum of two vectors. Faster but does not guarantee NaN behavior.

### `min(self, rhs: f64x4) -> f64x4`
Calculates the element-wise minimum of two vectors, handling NaNs by preferring the non-NaN value.

### `is_nan(self) -> f64x4`
Checks if each element is NaN.

### `is_finite(self) -> f64x4`
Checks if each element is finite.

### `is_inf(self) -> f64x4`
Checks if each element is infinite.

### `round(self) -> f64x4`
Rounds each element to the nearest integer.

### `round_int(self) -> i64x4`
Rounds each element to the nearest integer and returns an `i64x4` vector.

### `mul_add(self, m: f64x4, a: f64x4) -> f64x4`
Fused multiply-add operation: `(self * m) + a`.

### `mul_sub(self, m: f64x4, a: f64x4) -> f64x4`
Fused multiply-subtract operation: `(self * m) - a`.

### `mul_neg_add(self, m: f64x4, a: f64x4) -> f64x4`
Fused multiply-negate-add operation: `(self * m) + a`.

### `mul_neg_sub(self, m: f64x4, a: f64x4) -> f64x4`
Fused multiply-negate-subtract operation: `-(self * m) + a`.

### `flip_signs(self, signs: f64x4) -> f64x4`
Flips the sign of elements based on the corresponding element in the `signs` vector.

### `copysign(self, sign: f64x4) -> f64x4`
Copies the sign of the `sign` vector's elements to the `self` vector's elements.

### `asin_acos(self) -> (f64x4, f64x4)`
Calculates both the arcsine and arccosine of each element, returning a tuple of two `f64x4` vectors.

### `acos(self) -> f64x4`
Calculates the element-wise arccosine.

### `asin(self) -> f64x4`
Calculates the element-wise arcsine.

### `atan(self) -> f64x4`
Calculates the element-wise arctangent.

### `atan2(self, x: f64x4) -> f64x4`
Calculates the element-wise `atan2(self, x)`.

### `sin_cos(self) -> (f64x4, f64x4)`
Calculates both the sine and cosine of each element, returning a tuple of two `f64x4` vectors.

### `sin(self) -> f64x4`
Calculates the element-wise sine.

### `cos(self) -> f64x4`
Calculates the element-wise cosine.

### `tan(self) -> f64x4`
Calculates the element-wise tangent.

### `to_degrees(self) -> f64x4`
Converts each element from radians to degrees.

### `to_radians(self) -> f64x4`
Converts each element from degrees to radians.

### `sqrt(self) -> f64x4`
Calculates the element-wise square root.

### `move_mask(self) -> i32`
Converts the vector into a bitmask (integer representation).

### `any(self) -> bool`
Checks if any element in the vector evaluates to true (non-zero).

### `all(self) -> bool`
Checks if all elements in the vector evaluate to true (non-zero).

### `none(self) -> bool`
Checks if no elements in the vector evaluate to true (non-zero).

### `exp(self) -> f64x4`
Calculates the element-wise exponential (e^x).

### `reduce_add(self) -> f64`
Performs a horizontal addition of all elements in the vector.

### `ln(self) -> f64x4`
Calculates the element-wise natural logarithm.

### `log2(self) -> f64x4`
Calculates the element-wise base-2 logarithm.

### `log10(self) -> f64x4`
Calculates the element-wise base-10 logarithm.

### `pow_f64x4(self, y: f64x4) -> f64x4`
Calculates the element-wise power: `self` raised to the power of `y`.

### `powf(self, y: f64) -> f64x4`
Calculates the element-wise power: `self` raised to the power of a scalar `y`.

### `to_array(self) -> [f64; 4]`
Converts the `f64x4` vector into a 4-element array.

### `as_array_ref(&self) -> &[f64; 4]`
Returns a reference to the underlying 4-element array.

### `as_array_mut(&mut self) -> &mut [f64; 4]`
Returns a mutable reference to the underlying 4-element array.

### `from_i32x4(v: i32x4) -> f64x4`
Converts an `i32x4` vector to an `f64x4` vector.
```

--------------------------------

### Manual Particle Trait Implementation for Body Struct (Rust)

Source: https://docs.rs/particular/latest/src/particular/lib

Provides an example of manually implementing the `Particle` trait for a `Body` struct. This is useful when the struct's fields do not directly correspond to `position` and `mu`. It defines the `Array` type and implements `position` and `mu` methods.

```Rust
# const G: f32 = 1.0;
# use particular::prelude::*
# use ultraviolet::Vec3;
struct Body {
    position: Vec3,
    mass: f32,
//  ...
}

impl Particle for Body {
    type Array = [f32; 3];

    fn position(&self) -> [f32; 3] {
        self.position.into()
    }
    
    fn mu(&self) -> f32 {
        self.mass * G
    }
}
```

--------------------------------

### f64x4 Constructor and Basic Operations - Rust

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Details the static `new` method for creating an `f64x4` from an array of four `f64` values, along with fundamental operations like `blend`, `abs`, `floor`, `ceil`, and comparisons like `is_nan`, `is_finite`, and `is_inf`.

```rust
pub const fn new(array: [f64; 4]) -> f64x4
pub fn blend(self, t: f64x4, f: f64x4) -> f64x4
pub fn abs(self) -> f64x4
pub fn floor(self) -> f64x4
pub fn ceil(self) -> f64x4
pub fn is_nan(self) -> f64x4
pub fn is_finite(self) -> f64x4
pub fn is_inf(self) -> f64x4
```

--------------------------------

### Using Tuples as Particles in Rust

Source: https://docs.rs/particular/latest/index

This Rust example shows how to use a tuple directly as a particle, implementing the `Particle` trait implicitly. The tuple consists of a position (represented as an array) and a scalar value (mu). It demonstrates accessing the position and mu from the tuple, which can be useful when avoiding intermediate types.

```rust
let particle = ([1.0, 1.0, 0.0], 5.0);

assert_eq!(particle.position(), [1.0, 1.0, 0.0]);
assert_eq!(particle.mu(), 5.0);
```

--------------------------------

### f64x4 Equality Comparison (`PartialEq`)

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Tests for equality and inequality between f64x4 values.

```APIDOC
## POST /f64x4/eq

### Description
Tests for equality between two f64x4 values.

### Method
POST

### Endpoint
/f64x4/eq

### Parameters
#### Request Body
- **self** (f64x4) - Required - The first f64x4 value.
- **other** (f64x4) - Required - The second f64x4 value.

### Request Example
```json
{
  "self": [1.0, 2.0, 3.0, 4.0],
  "other": [1.0, 2.0, 3.0, 4.0]
}
```

### Response
#### Success Response (200)
- **result** (bool) - True if the values are equal, false otherwise.

#### Response Example
```json
{
  "result": true
}
```

## POST /f64x4/ne

### Description
Tests for inequality between two f64x4 values.

### Method
POST

### Endpoint
/f64x4/ne

### Parameters
#### Request Body
- **self** (f64x4) - Required - The first f64x4 value.
- **other** (f64x4) - Required - The second f64x4 value.

### Request Example
```json
{
  "self": [1.0, 2.0, 3.0, 4.0],
  "other": [1.0, 2.0, 3.0, 5.0]
}
```

### Response
#### Success Response (200)
- **result** (bool) - True if the values are not equal, false otherwise.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### DynamicBuffer Management in Rust for wgpu

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu_compute/mod

Manages a `wgpu::Buffer` that can be dynamically resized and written to. It simplifies buffer creation, writing data, resizing, and accessing buffer properties within a `wgpu` compute context. Dependencies include `wgpu` and `ultraviolet` for vector types.

```rust
use ultraviolet::{Vec3, Vec4};
use wgpu::util::{BufferInitDescriptor, DeviceExt};

struct DynamicBuffer {
    buffer: wgpu::Buffer,
    label: Option<String>,
}

impl DynamicBuffer {
    fn new(device: &wgpu::Device, descriptor: &wgpu::BufferDescriptor) -> Self {
        DynamicBuffer {
            buffer: device.create_buffer(descriptor),
            label: descriptor.label.map(String::from),
        }
    }

    fn write(&mut self, device: &wgpu::Device, queue: &wgpu::Queue, contents: &[u8]) {
        if self.buffer.size() == contents.len() as wgpu::BufferAddress {
            queue.write_buffer(&self.buffer, 0, contents);
        } else {
            self.buffer = device.create_buffer_init(&BufferInitDescriptor {
                contents,
                label: self.label.as_deref(),
                usage: self.buffer.usage(),
            });
        }
    }

    fn resize(&mut self, device: &wgpu::Device, size: wgpu::BufferAddress) {
        self.buffer = device.create_buffer(&wgpu::BufferDescriptor {
            size,
            mapped_at_creation: false,
            label: self.label.as_deref(),
            usage: self.buffer.usage(),
        });
    }

    fn buffer(&self) -> &wgpu::Buffer {
        &self.buffer
    }

    fn size(&self) -> wgpu::BufferAddress {
        self.buffer.size()
    }
}
```

--------------------------------

### MemoryStrategy Enum for Compute Shaders in Rust

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu_compute/mod

Defines how massive particle data is accessed in compute shaders using either shared or global memory. It includes methods to get the corresponding shader source code and the workgroup size. This enum is crucial for optimizing memory access patterns on the GPU. Dependencies include `wgpu`.

```rust
/// Defines the way memory for massive particles is accessed in the compute shader.
#[derive(Debug, Clone, Copy)]
pub enum MemoryStrategy {
    /// Uses shared memory to store the massive particles and speed up memory access within one
    /// workgroup. Based on https://developer.nvidia.com/gpugems/gpugems3/part-v-physics-simulation/chapter-31-fast-n-body-simulation-cuda.
    Shared(u32),
    /// Uses global memory to store and access the massive particles.
    Global(u32),
}

impl Default for MemoryStrategy {
    #[inline]
    fn default() -> Self {
        MemoryStrategy::Global(256)
    }
}

impl MemoryStrategy {
    /// Returns the processed shader for the given [`MemoryStrategy`].
    #[inline]
    pub fn as_shader_source(&self) -> wgpu::ShaderSource {
        let (concat, workgroup_size) = match self {
            MemoryStrategy::Shared(workgroup_size) => (
                concat!(
                    include_str!("particle.wgsl"),
                    include_str!("compute_shared.wgsl")
                ),
                workgroup_size,
            ),
            MemoryStrategy::Global(workgroup_size) => (
                concat!(include_str!("particle.wgsl"), include_str!("compute.wgsl")),
                workgroup_size,
            ),
        };
        wgpu::ShaderSource::Wgsl(
            concat
                .replace("#WORKGROUP_SIZE", &(workgroup_size.to_string() + "u"))
                .into(),
        )
    }

    /// Returns the workgroup size for the shader of this [`MemoryStrategy`].
    #[inline]
    pub fn workgroup_size(&self) -> u32 {
        match self {
            MemoryStrategy::Shared(workgroup_size) => *workgroup_size,
            MemoryStrategy::Global(workgroup_size) => *workgroup_size,
        }
    }
}
```

--------------------------------

### Manage WGPU Resources State in Rust

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu

Manages the state of WGPU resources for GPU computations. It handles initialization and provides access to WgpuResources, ensuring they are ready for use. This is crucial for efficient GPU data processing.

```rust
use {
    crate::compute_method::gpu_compute::WgpuResources,
    crate::compute_method::storage::{ParticleSliceSystem, PointMass},
    crate::compute_method::ComputeMethod,
};
use ultraviolet::Vec3;

pub use crate::compute_method::gpu_compute::MemoryStrategy;

enum GpuResourcesState {
    New(MemoryStrategy),
    Init(WgpuResources),
}

impl GpuResourcesState {
    /// Returns a mutable reference to the [`WgpuResources`] if it is initialised.
    #[inline]
    fn get_or_init(&mut self, device: &wgpu::Device) -> &mut WgpuResources {
        if let Self::New(workgroup_size) = self {
            *self = Self::Init(WgpuResources::new(device, *workgroup_size));
        }

        match self {
            Self::Init(resources) => resources,
            _ => unreachable!(),
        }
    }
}

/// Resources used by `wgpu` for computing on the GPU.
pub struct GpuResources(GpuResourcesState);

impl GpuResources {
    /// Creates a new [`GpuResources`] instance.
    #[inline]
    pub fn new(shader_type: MemoryStrategy) -> Self {
        Self(GpuResourcesState::New(shader_type))
    }

    /// Creates a new [`GpuResources`] instance with initialised buffers and pipeline.
    #[inline]
    pub fn init(shader_type: MemoryStrategy, device: &wgpu::Device) -> Self {
        Self(GpuResourcesState::Init(WgpuResources::new(
            device,
            shader_type,
        )))
    }

    /// Returns a mutable reference to the [`WgpuResources`] if it is initialised.
    #[inline]
    pub fn get_or_init(&mut self, device: &wgpu::Device) -> &mut WgpuResources {
        self.0.get_or_init(device)
    }
}
```

--------------------------------

### f64x4 Static Methods

Source: https://docs.rs/particular/latest/particular/compute_method/math/struct

Provides static methods for creating f64x4 vectors.

```APIDOC
## f64x4 Static Methods

### `splat(elem: f64) -> f64x4`
Creates a new `f64x4` vector where all elements are set to the provided `elem` value.
```

--------------------------------

### Rust wgpu Compute Accelerations and Readback

Source: https://docs.rs/particular/latest/src/particular/compute_method/gpu_compute/mod

This snippet demonstrates how to use wgpu to perform a compute operation on acceleration data, copy the results to a staging buffer, and then asynchronously read the data back to the CPU. It involves creating a command encoder, setting up a compute pass, dispatching workgroups, and using flume channels for asynchronous operations. Dependencies include `wgpu` and `flume`.

```Rust
        let encoder_descriptor = wgpu::CommandEncoderDescriptor { label: None };
        let mut encoder = device.create_command_encoder(&encoder_descriptor);

        encoder.push_debug_group("Compute accelerations");
        {
            let workgroups = (affected_count as f32 / self.workgroup_size as f32).ceil() as u32;
            let compute_pass_descriptor = wgpu::ComputePassDescriptor::default();
            let mut compute_pass = encoder.begin_compute_pass(&compute_pass_descriptor);
            compute_pass.set_pipeline(&self.pipeline);
            compute_pass.set_push_constants(0, bytemuck::cast_slice(&[softening * softening]));
            compute_pass.set_bind_group(0, &bind_group, &[]);
            compute_pass.dispatch_workgroups(workgroups, 1, 1);
        }
        encoder.pop_debug_group();

        let buffer_staging = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("Staging buffer"),
            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
            size: self.buffer_accelerations.size(),
            mapped_at_creation: false,
        });

        encoder.copy_buffer_to_buffer(
            self.buffer_accelerations.buffer(),
            0,
            &buffer_staging,
            0,
            self.buffer_accelerations.size(),
        );

        queue.submit([encoder.finish()]);

        let (sender, receiver) = flume::bounded(1);

        let buffer = buffer_staging.slice(..);
        buffer.map_async(wgpu::MapMode::Read, move |r| sender.send(r).unwrap());

        device.poll(wgpu::Maintain::Wait);
        receiver
            .recv_async()
            .await
            .unwrap()
            .expect("Could not read buffer");

        let view = buffer.get_mapped_range();
        let accelerations = bytemuck::cast_slice(&view)
            .iter()
            .map(Vec4::truncated)
            .collect();

        drop(view);
        buffer_staging.unmap();

        accelerations
    }
}
```

--------------------------------

### Rust: Compute Accelerations on GPU

Source: https://docs.rs/particular/latest/particular/compute_method/gpu_compute/struct

Implements the asynchronous `compute` method for WgpuResources. This function executes the GPU computation, returning the calculated accelerations as a Vec<Vec3>. It requires the wgpu device, queue, and a softening factor for the computation. The `async` keyword indicates that this operation may involve waiting for GPU operations to complete.

```rust
pub async fn compute( &self, device: &Device, queue: &Queue, softening: f32, ) -> Vec<Vec3>
```

--------------------------------

### Particle System with Barnes-Hut (Rust)

Source: https://docs.rs/particular/latest/index

Illustrates the usage of `ParticleSystem` and `ParticleTree` for efficient gravitational force computation using the Barnes-Hut algorithm. It shows how to build a tree from massive particles and then compute accelerations on affected (massless) particles. This approach optimizes calculations by grouping distant particles.

```rust
use particular::math::Vec3;

let particles = vec![
    // ...
];

// Create a `ParticleOrdered` to split massive and massless particles.
let ordered = ParticleOrdered::from(&*particles);

// Build a `ParticleTree` from the massive particles.
let tree = ParticleTree::from(ordered.massive());

// Do something with the tree.
for (node, data) in std::iter::zip(&tree.get().nodes, &tree.get().data) {
    // ...
}

let bh = &mut sequential::BarnesHut { theta: 0.5 };
// The implementation computes the acceleration exerted on the particles in
// the `affected` slice.
// As such, this only computes the acceleration of the massless particles.
let accelerations = bh.compute(ParticleSystem {
    affected: ordered.massless(),
    massive: &tree,
});
```
Tokens:
Raw