Dokumentasi Natumpy

Natumpy adalah pustaka eksperimen numerik hibrida Python/C++ yang dirancang untuk simulasi fisika partikel berbasis Damped Harmonic Oscillator dengan performa tinggi.

Fitur Utama:

• Inti C++ Berkinerja Tinggi: Menangani kalkulasi fisika (kecepatan, gaya, redaman) di level rendah.
• Integrasi NumPy Zero-Copy: Data fisika diakses langsung oleh Python tanpa penyalinan memori, memungkinkan analisis data *real-time* yang sangat cepat.
• Thread-Safe: Mendukung komputasi paralel pada level C++.

Instalasi

Natumpy memerlukan kompilator C++17 dan pustaka pengembangan Python.

Prasyarat

pip install numpy setuptools

Build dari Sumber

# 1. Clone repositori atau ekstrak source code
# 2. Masuk ke direktori root
cd natumpy/

# 3. Install dalam mode development atau production
pip install .

Konsep Inti

Natumpy memodelkan sekumpulan atom dalam 1D array. Setiap atom memiliki struktur memori 40-byte:

Panduan Cepat

Contoh sederhana membuat satu atom bergerak menuju targetnya.

import natumpy
import numpy as np
import time

# 1. Buat field dengan 10 atom
field = natumpy.create_field(10)

# 2. Dapatkan view NumPy (Manipulasi properti)
arr = natumpy.view(field)

# Set properti awal
arr['mass'][:] = 2.0        # Set massa semua atom
arr['damping'][:] = 0.05    # Sedikit redaman
arr['target'][5] = 100.0    # Atom ke-5 ingin pergi ke posisi 100

print(f"Posisi Awal Atom 5: {arr['value'][5]:.2f}")

# 3. Jalankan Simulasi
# 500 siklus fisika dengan delta time 0.1
field.step(500, 0.1)

print(f"Posisi Akhir Atom 5: {arr['value'][5]:.2f}")
print(f"Kecepatan Akhir: {arr['velocity'][5]:.2f}")

API Reference

natumpy.create_field(size)

Membuat instance mesin fisika baru.

• size (int): Jumlah atom yang akan disimulasikan.
• Returns: Objek NatField.

natumpy.view(field)

Membuat NumPy array terstruktur yang menunjuk ke memori C++ field tersebut.

• Returns: numpy.ndarray dengan dtype khusus (value, velocity, mass, damping, target).

Metode Objek NatField

.step(cycles, dt)

Menjalankan langkah simulasi fisika.

• cycles (int): Berapa kali loop fisika dijalankan.
• dt (float): Delta time (langkah waktu). Default: 0.1.

.set_props(index, mass, damping)

Mengatur properti fisik atom tertentu secara manual (alternatif dari penggunaan NumPy view).

.resonate(idx_a, idx_b, strength)

Menciptakan kopling (hubungan gaya) antara dua atom. Jika atom A bergerak, atom B akan terpengaruh, dan sebaliknya.

• strength (float): Kekuatan hubungan antarat atom.

.force(index, value)

Memaksa posisi atom ke nilai tertentu dan me-reset kecepatannya menjadi 0.

Contoh Lanjut: Simulasi Gelombang

Berikut adalah contoh bagaimana membuat simulasi gelombang mekanik sederhana dengan menghubungkan atom tetangga menggunakan resonate.

import natumpy
import numpy as np

SIZE = 100
field = natumpy.create_field(SIZE)
arr = natumpy.view(field)

# Konfigurasi Awal
arr['damping'][:] = 0.01  # Redaman sangat rendah agar gelombang menjalar
arr['mass'][:] = 1.0

# Buat gangguan awal di tengah
field.force(50, 50.0) 

print("Simulasi Gelombang Dimulai...")

# Loop simulasi
for t in range(10):
    # 1. Resonansi: Hubungkan setiap atom dengan tetangganya
    # Ini menciptakan efek "tali" atau "pegas" antar atom
    for i in range(SIZE - 1):
        field.resonate(i, i+1, 0.5) # Strength 0.5
    
    # 2. Langkah Fisika
    field.step(10, 0.1)
    
    # 3. Output visual sederhana (ASCII art)
    peak = np.argmax(arr['value'])
    val = arr['value'][peak]
    print(f"Step {t}: Puncak gelombang di index {peak} (Tinggi: {val:.2f})")