shipstab 0.1.0

Python Ship Stability Library

shipstab 🚢

Python Gemi Stabilitesi Kütüphanesi

shipstab, gemi stabilitesi hesaplamalarını Python ile yapabilmek için tasarlanmış açık kaynaklı bir kütüphanedir. Denizcilik mühendisliği bilgisini modern Python ekosistemine (NumPy, SciPy, Matplotlib) entegre eder.

---

Özellikler

Modül	İçerik
core.Hull	Ofset tablosundan tekne geometrisi, hacim / alan entegrasyonu
core.Hydrostatics	Δ, KB, BM, KM, TPC, MTC, LCB, LCF, Cb, Cw tablosu
core.BonjeanCurves	Bonjean eğrileri
stability.IntactStability	GZ eğrisi, GM, AVS, dinamik stabilite alanı
stability.IMOCriteria	IS Code 2008 — 6 temel kriter + rüzgar kriteri
stability.DamageStability	Added Weight & Lost Buoyancy yöntemleri
stability.DynamicStability	Righting energy, doğal salınım periyodu
loading.Tank	Serbest yüzey etkisi (FSC), çoklu sıvı türü
loading.CargoItem	Genel / konteyner / dökme kargo
loading.LoadCase	Yükleme durumu toplamı, KG/LCG/TCG hesabı
trim.TrimCalculator	Trim & list, kıç/baş draftları, kütle kaydırma
reports.StabilityReport	GZ grafiği, hidrostatik eğriler, CSV export

---

Kurulum

# Temel kurulum
pip install shipstab

# Grafik desteğiyle
pip install shipstab[plot]

# Tam kurulum (grafik + PDF rapor)
pip install shipstab[report]

# Geliştirici kurulumu
git clone https://github.com/yourusername/shipstab.git
cd shipstab
pip install -e ".[dev,plot,report]"

---

Hızlı Başlangıç

1. Hull Oluşturma

from shipstab import Hull, Vessel

# Ofset tablosu: {istasyon_x: {su_hattı_z: yarı_genişlik_y}}
offsets = {
    0.0:  {0.0: 0.0, 2.0: 2.5, 4.0: 4.2, 6.0: 5.0, 8.0: 5.5, 10.0: 5.8},
    20.0: {0.0: 0.5, 2.0: 4.0, 4.0: 5.8, 6.0: 6.8, 8.0: 7.2, 10.0: 7.5},
    40.0: {0.0: 1.0, 2.0: 5.0, 4.0: 6.8, 6.0: 7.5, 8.0: 7.8, 10.0: 8.0},
    60.0: {0.0: 1.0, 2.0: 5.0, 4.0: 6.8, 6.0: 7.5, 8.0: 7.8, 10.0: 8.0},
    80.0: {0.0: 0.5, 2.0: 4.0, 4.0: 5.8, 6.0: 6.8, 8.0: 7.2, 10.0: 7.5},
   100.0: {0.0: 0.0, 2.0: 2.5, 4.0: 4.2, 6.0: 5.0, 8.0: 5.5, 10.0: 5.8},
}

hull = Hull(offsets, LBP=100.0)

2. Vessel & Yükleme Durumu

from shipstab import Vessel, Tank, CargoItem, LoadCase
from shipstab.loading.tank import TankType
from shipstab.loading.loadcase import LightShipData

# Gemi oluştur
vessel = Vessel("MV Denizci", hull)
vessel.prepare_hydrostatics()          # Hidrostatik tabloyu ön-hesapla

# Yükleme durumu
lightship = LightShipData(
    displacement=3200.0,   # t
    lcg=50.0,              # m kıçtan
    vcg=6.8,               # m köşeden (KG_LS)
)

lc = LoadCase("Hareket — Tam Yük", lightship)

# Tanklar
lc.add_tank(Tank(
    name="FO_DB_PORT", length=12, breadth=8, height=1.8,
    fill_ratio=0.92, lcg=18.0, tcg=-4.0, vcg=0.9,
    tank_type=TankType.FUEL_OIL,
))
lc.add_tank(Tank(
    name="BW_DB_STBD", length=15, breadth=8, height=2.0,
    fill_ratio=1.00, lcg=30.0, tcg=+4.0, vcg=1.0,
    tank_type=TankType.BALLAST,
))
lc.add_tank(Tank(
    name="FW_TANK",    length=6,  breadth=6, height=2.5,
    fill_ratio=0.65, lcg=55.0, tcg=0.0, vcg=8.5,
    tank_type=TankType.FRESH_WATER,
))

# Kargo
lc.add_cargo(CargoItem("Genel Kargo #1", mass=850.0, lcg=45.0, vcg=9.2))
lc.add_cargo(CargoItem("Genel Kargo #2", mass=620.0, lcg=60.0, vcg=9.5))

# Vessel'a uygula
vessel.apply_load_case(lc)
lc.print_table()

3. Stabilite Kontrolü

# IMO IS Code 2008 kriterleri
vessel.check_stability()

# Detaylı GZ özeti
from shipstab.stability.intact import IntactStability
st = IntactStability(vessel)
print(st.summary())

4. Trim Hesabı

vessel.trim_summary()

5. Grafik & Rapor

from shipstab import StabilityReport

rep = StabilityReport(vessel)

# GZ eğrisi
fig = rep.plot_GZ_curve(save_path="gz_curve.png")
fig.show()

# Tam özet
rep.print_stability_summary()

# CSV export
rep.export_hydrostatic_csv("hydrostatics.csv")
rep.export_GZ_csv("gz_values.csv")

6. Hasar Stabilitesi

from shipstab.stability.damage import DamageStability, DamageCase, CompartmentGeometry

# Bölmeleri tanımla
ds = DamageStability(vessel)
ds.add_compartment(CompartmentGeometry(
    name="CARGO_HOLD_2",
    x_aft=40.0, x_fwd=60.0,
    y_port=6.0, y_stbd=6.0,
    z_bottom=1.0, z_top=8.0,
))

# Hasar senaryosu
case = DamageCase(
    name="Hold_2_Flooded",
    compartments=["CARGO_HOLD_2"],
    permeability=0.60,
    method="added_weight",
)

result = ds.analyse(case)
print(result)
# {'new_GM': 0.42, 'list_deg': 1.3, 'new_draft': 7.84, ...}

---

API Referansı (Özet)

Hull

hull.waterplane_area(draft)         # Su hattı alanı (m²)
hull.volume_of_displacement(draft)  # Yerinden etme hacmi (m³)
hull.KB(draft)                      # Şamandıra merkezi yüksekliği (m)
hull.LCB(draft)                     # Boyuna şamandıra merkezi (m)
hull.LCF(draft)                     # Su hattı alan merkezi (m)
hull.Cb(draft)                      # Blok katsayısı

Hydrostatics

hydro.at_draft(draft)               # Tüm değerler dict
hydro.generate_table()              # Tam tablo
hydro.KM(draft)                     # Interpolasyon ile KM
hydro.TPC(draft)                    # Interpolasyon ile TPC
hydro.displacement(draft)           # Deplasman (t)
hydro.draft_from_displacement(disp) # Ters interpolasyon
hydro.print_table()                 # Konsola yazdır

IntactStability

st.GM                               # Metasantr yüksekliği
st.GZ_at_angle(deg)                 # Tek açıda GZ
st.GZ_curve(angles)                 # Tam GZ eğrisi
st.dynamic_stability_area(a1, a2)   # e(a1→a2) m·rad
st.angle_of_maximum_GZ()            # (açı, GZ_max)
st.angle_of_vanishing_stability()   # AVS açısı
st.summary()                        # Özet dict

Tank

tank.mass                           # Kütle (t)
tank.free_surface_moment            # FSM (t·m)
tank.virtual_rise_of_G(disp)        # GG' (m)
tank.fill_to(ratio)                 # Doluluk ayarla

TrimCalculator

tc.draughts()                       # T_AP, T_FP, trim
tc.list_angle()                     # List açısı (°)
tc.trim_from_adding_mass(m, lcg)    # Kütle ekleme etkisi
tc.list_from_shifting_mass(m, d)    # Kütle kaydırma etkisi

---

Testleri Çalıştırma

cd shipstab
pytest tests/ -v --cov=shipstab

---

Katkı

1. Fork edin
2. Feature branch açın (git checkout -b feature/yeni-ozellik)
3. Değişiklikleri commit edin (git commit -m 'feat: yeni özellik')
4. Push edin (git push origin feature/yeni-ozellik)
5. Pull Request açın

---

Lisans

MIT License — Detaylar için LICENSE dosyasına bakın.

---

Yol Haritası

• Tam 3-D GZ hesabı (hacim entegrasyonu ile)
• SOLAS hasar stabilitesi kriterleri
• PDF rapor (ReportLab)
• CLI aracı (shipstab check vessel.json)
• MARPOL Ek I tanker kriterleri
• Web API (FastAPI)
• Türkçe / İngilizce dokümantasyon sitesi