NewtonGrid — 3D Gravitational Field Simulation

Description

NewtonGrid is a 3D gravitational field simulator written in C++ that computes and visualizes vector fields produced by point masses on a discrete domain. The project adopts a scientific-computing approach to solve Newton’s Universal Law of Gravitation on regular Cartesian grids, with export support for formats compatible with ParaView.

---

Key Features

• Flexible 3D Cartesian grid: customizable domains (dimensions, spacing, and origin).
• Multiple configuration modes: masses defined manually, symmetrically, randomly, or via file.
• Realistic physics: implementation of the Universal Law of Gravitation with softening for numerical stability.
• VTK export: generates .vti (VTK Image Data) files for professional 3D visualization.
• Interactive interface: terminal menu with step-by-step input and data validation.
• Cross-platform: Linux, macOS and Windows (ANSI/VT colors).

Gravitational field produced by point masses — magnitude visualization.

Another view of the field, used for visual validation.

---

Project structure

src/
├── NewtonGrid.cpp              # Main program with interactive interface
├── data/
│   ├── Grid.hpp                # 3D grid representation
│   └── FieldData.hpp           # Storage for vector fields
├── physics/
│   └── GravitationalField.hpp  # Gravitational field computation
├── io/
│   └── VTIWriter.hpp           # VTK Image Data (.vti) exporter
└── output.vti                  # File generated after execution

---

Class architecture

1. Grid (Grid.hpp)

Represents a regular 3D Cartesian domain.

Characteristics:

• Always 3D (2D supported via nz = 1).
• Contiguous memory with F-contiguous ordering (x fastest).
• Immutable interface after construction.
• Efficient conversions between discrete indices, linear index, and physical coordinates.
• Compatible with VTK ImageData.

Main methods:

• dimensions(), spacing(), origin()
• linear_index(i, j, k)
• discrete_indices(idx)
• physical_to_discrete(x, y, z)
• discrete_to_physical(i, j, k)
• for_each_point(func)

---

2. FieldData (FieldData.hpp)

Stores a 3D vector field defined on a Grid.

Characteristics:

• Separate component storage (gx, gy, gz).
• Bulk operations (zeroing, filling, applying functions).
• Derived quantity calculations (magnitude, L2 norm).
• Conversion to Array-of-Structures (AOS) for export.

Main methods:

• allocate(grid, zero_init)
• get_vector(idx), set_vector(idx, vec)
• magnitude(idx)
• max_magnitude(), min_positive_magnitude(), norm_l2()
• to_aos()

---

3. GravitationalField (GravitationalField.hpp)

Computes Newtonian gravitational fields generated by point masses.

Characteristics:

• Implements the Universal Law of Gravitation with softening.
• Supports multiple masses.
• Read thread-safe.
• Prepared for optimizations (SIMD, OpenMP).

Main methods:

• add_mass(x, y, z, value)
• compute(field)
• compute_optimized(field)
• compute_magnitude_only(field)
• compute_potential(field)

---

4. VTIWriter (VTIWriter.hpp)

Exports data to the VTK ImageData (.vti) format.

Characteristics:

• XML files compatible with ParaView.
• Exports both the vector field and its magnitude.
• Configurable precision (default: 15 digits).
• ASCII format (human-readable).

Main methods:

• write(filename, grid, field)
• set_precision(precision)
• enable_magnitude(enabled)
• enable_vector_field(enabled)

---

Prerequisites

• C++17 compiler (g++ 7+, clang 5+, MSVC 2019+)
• Terminal with ANSI color support
• ParaView (optional, for visualization)

---

Compilation

Linux / macOS

# g++
g++ -std=c++17 -O2 -I. NewtonGrid.cpp -o NewtonGrid -pthread

# clang
clang++ -std=c++17 -O2 -I. NewtonGrid.cpp -o NewtonGrid -pthread

Windows

# MinGW
g++ -std=c++17 -O2 -I. NewtonGrid.cpp -o NewtonGrid.exe

# MSVC (Developer Command Prompt)
cl /EHsc /std:c++17 /O2 NewtonGrid.cpp

---

Usage

Interactive run

Program screen showing the interactive menu.

./NewtonGrid

The program guides the user through an interactive menu:

1. Choose the grid (preset or custom)
2. Set G and softening
3. Configure the masses
4. Compute the field
5. Export to output.vti

---

Non-interactive (pipeline) run

echo -e "2\n1.0\n0.001\n1\n2\n1.0 0.0 0.0 5.0\n-1.0 0.0 0.0 5.0" | ./NewtonGrid

---

Viewing results

Graphical editor used to inspect and tweak the VTI output.

1. Install ParaView
2. Open output.vti
3. Apply filters such as Glyph, Contour, or Slice
4. Adjust scale, colors and magnitude as needed

---

Mass file format

# x y z mass
0.0 0.0 0.0 1.0
1.0 0.0 0.0 0.5
-1.0 0.0 0.0 0.5

---

Example use cases

1. Binary system

./NewtonGrid
# Choice: Medium Grid (50x50x50)
# G = 1.0, softening = 0.001
# Masses: Symmetric, 2 masses, separation = 3.0, mass = 5.0

2. Stellar cluster

./NewtonGrid
# Grid: Large (100x100x100)
# Masses: Random, 10 masses, minimum distance = 1.0, varying masses

3. Single well (point mass)

./NewtonGrid
# Grid: Custom (nx=64, ny=64, nz=1, dx=dy=0.1, dz=1.0)
# Masses: Manual, position (0,0,0), mass = 10.0

---

Program output

Representative image of the generated output (vectors and magnitudes).

The program produces:

• Grid statistics: dimensions, spacing, origin, total points
• Mass list: positions and values of all masses
• Field statistics: maximum/minimum magnitude, L2 norm
• output.vti file: VTK-formatted data for visualization
• Validation examples: field values at selected points for verification

---

Implemented physics

Universal Law of Gravitation

$$\vec{g} = -G \cdot m \cdot \frac{\vec{r}}{(\lVert r \rVert^2 + \varepsilon^2)^{3/2}}$$

Where:

• G: gravitational constant
• \vec{r}: displacement vector
• \varepsilon: softening parameter