Dokumentacja Kodu (API)

Backend (Python / FastAPI)

Logika API (routes.py)

routes.get_isotope_decay_chain(nazwa: str)

Zwraca strukturę grafu izotopu wraz z jego przodkami i potomkami w formacie Cytoscape.

Endpoint odpytuje bazę Neo4j w celu znalezienia ścieżek do 15 kroków w dół (w co rozpada się izotop) oraz do 15 kroków w górę (co rozpada się w ten izotop). Przekształca wyniki na format zgodny z biblioteką frontendową Cytoscape.js.

Parametry:

nazwa (str) – Nazwa głównego (centralnego) izotopu dla grafu (np. «U-238»).

Zwraca:

Lista węzłów i krawędzi (relacji) sformatowana dla Cytoscape.js. Zawiera parametry takie jak id, label, type, source, target oraz prawdopodobieństwo rozpadu.

Typ zwracany:

list[dict]

routes.get_isotope_details(nazwa: str)

Pobiera szczegółowe dane fizyczne dla konkretnego izotopu.

Wyszukuje w bazie grafowej Neo4j węzeł odpowiadający podanej nazwie. Jeśli w bazie zapisane są dane widma (w formacie JSON), zostają one zdeserializowane.

Parametry:

nazwa (str) – Pełna nazwa izotopu (np. «U-238»).

Wyrzuca:

HTTPException – Kod 404, jeśli izotop o podanej nazwie nie istnieje w bazie.

Zwraca:

Szczegółowe parametry izotopu obejmujące liczbę Z, A, czas półtrwania, prawdopodobieństwo spontanicznego rozszczepienia (sf_prob) oraz widmo.

Typ zwracany:

dict

routes.get_isotope_evolution(nazwa: str)

Oblicza ewolucję łańcucha rozpadu w czasie wykorzystując równania Batemana.

Na podstawie biblioteki radioactivedecay symuluje populację izotopów potomnych w 50 równych krokach czasowych. Całkowity czas symulacji wynosi 5 czasów półtrwania badanego izotopu. Izotopy stabilne oraz posiadające nieskończony czas półtrwania są pomijane w obliczeniach ewolucji.

Parametry:

nazwa (str) – Nazwa izotopu początkowego (np. «U-238»).

Zwraca:

Wyniki symulacji zawierające flagę stable, czas półtrwania w sekundach (half_life_s) oraz listę data, w której każdy element to stan ilościowy izotopów w danym kroku czasowym.

Typ zwracany:

dict

routes.get_segre_chart_data()

Pobiera minimalny zestaw danych o wszystkich izotopach niezbędny do wyrysowania siatki na frontendzie.

Przeszukuje bazę Neo4j i wyciąga podstawowe parametry (liczbę atomową Z, liczbę masową A oraz czas półtrwania). Na podstawie czasu półtrwania przypisuje izotopom flagę stabilności.

Zwraca:

Lista słowników zawierająca dane izotopów. Każdy słownik posiada klucze: nazwa, Z, A, czas_poltrwania, nazwa_pierwiastka oraz typ.

Typ zwracany:

list[dict]

Baza Danych (database.py)

class database.Neo4jConnection

close()

Bezpiecznie zamyka aktywne połączenie (sterownik) z bazą Neo4j.

Inicjalizacja (main.py)

main.lifespan(app: FastAPI)

Zarządza cyklem życia aplikacji FastAPI.

Asynchroniczny menedżer kontekstu zastępujący zdarzenia «startup» i «shutdown». Kod znajdujący się przed instrukcją yield wykonuje się podczas startu serwera, natomiast kod po yield gwarantuje bezpieczne zwolnienie zasobów przy wyłączaniu aplikacji (w tym przypadku zamyka połączenie ze sterownikiem bazy Neo4j).

Parametry:

app (FastAPI) – Główna instancja aplikacji FastAPI.

Skrypt zasilający (populate_db.py)

populate_db.populate_entire_database()

Kompleksowo zasila bazę grafową Neo4j pełnymi danymi izotopów i relacjami rozpadów.

Funkcja usuwa dotychczasowe dane z bazy, a następnie pobiera pełną listę izotopów z biblioteki radioactivedecay. Dla każdego niestabilnego izotopu wyciąga parametry (Z, A, czas półtrwania, prawdopodobieństwo SF), dołącza dane widm z pliku JSON wygenerowanego na podstawie biblioteki PyNE i zapisuje jako węzły w Neo4j. Odtwarza również drzewo rozpadów, tworząc relacje (np. ROZPAD_ALFA, ROZPAD_BETA_MINUS) pomiędzy izotopami, a na koniec łączy je z odpowiednimi węzłami Pierwiastków chemicznych.

Informacja

Wymaga dostępu do bazy Neo4j skonfigurowanej za pomocą zmiennych środowiskowych NEO4J_URI, NEO4J_USER oraz NEO4J_PASSWORD.

Frontend (JavaScript)

Logika siatki izotopów (app.js)

getIsomerLevel(name)

Określa poziom stanu izomerycznego (wzbudzenia) izotopu na podstawie jego nazwy.

Analizuje sufiksy w nazwie izotopu (takie jak «m», «m1», «n», «p»), aby sklasyfikować go jako stan podstawowy lub jeden ze stanów wzbudzonych. Wykorzystywane do filtrowania warstw na głównym wykresie.

Argumenty:

• name (string) – Nazwa izotopu do weryfikacji (np. „Tc-99m”).

Zwraca:

number – Liczba całkowita reprezentująca poziom wzbudzenia: 0 (stan podstawowy), 1, 2 lub 3.

getColorForHalfLife(hlStr)

Konwertuje tekstowy czas półtrwania na odpowiedni kolor na mapie izotopów.

Rozpoznaje jednostki czasu (od nanosekund po lata), przelicza wartość na sekundy, a następnie używa skali logarytmicznej do wygenerowania odpowiedniego koloru z predefiniowanej palety termicznej (od czerwonego do niebieskiego). Izotopy stabilne są rysowane na czarno.

Argumenty:

• hlStr (string) – Czas półtrwania w postaci tekstowej wraz z jednostką (np. „4.468e9 y”, „Stable”).

Zwraca:

string – Kod koloru w formacie HEX przypisany do danego czasu półtrwania.

renderChart(levelFilter)

Rysuje lub aktualizuje siatkę izotopów na głównym wykresie D3.

Pobiera pełny zbiór izotopów i filtruje go według wybranego poziomu izomerycznego. Tworzy elementy SVG w odpowiednich koordynatach Z i N. Podpina również zdarzenia myszy do wyświetlania dynamicznych tooltipów oraz otwierania panelu bocznego po kliknięciu.

Argumenty:

• levelFilter (number) – Poziom stanu izomerycznego (0-3), który ma zostać wyrenderowany.

Zwraca:

void – Modyfikuje bezpośrednio wyselekcjonowaną grupę SVG w DOM.

openPanel(isotope)

Otwiera panel boczny i wypełnia go podstawowymi danymi wybranego izotopu.

Aktualizuje węzły tekstowe w DOM na podstawie przekazanego obiektu, zdejmując z panelu klasę ukrywającą go przed użytkownikiem.

Argumenty:

• isotope (Object) – Obiekt reprezentujący wybrany izotop (musi zawierać nazwę, Z, A, czas półtrwania oraz nazwę pierwiastka).

Zwraca:

void – Modyfikuje bezpośrednio zawartość panelu w strukturze DOM.

Logika szczegółów (details.js)

drawBranchingChart(edgesData, centralNodeId)

Rysuje wykres kołowy (donut chart) przedstawiający prawdopodobieństwa poszczególnych dróg rozpadu dla badanego izotopu.

Funkcja filtruje krawędzie wychodzące z głównego izotopu, zamienia ich prawdopodobieństwa na procenty i renderuje wykres SVG przy użyciu biblioteki D3.js. Jeśli izotop jest stabilny (brak krawędzi wychodzących), wyświetla stosowny komunikat tekstowy zamiast wykresu.

Argumenty:

• edgesData (Array.<Object>) – Lista obiektów krawędzi (z grafu Cytoscape) zawierających dane o relacjach i prawdopodobieństwach rozpadu.

• centralNodeId (string) – Identyfikator (nazwa) głównego izotopu, dla którego analizowane są rozpadu wychodzące.

Zwraca:

void – Funkcja modyfikuje bezpośrednio drzewo DOM, niczego nie zwracając.

drawEvolutionChart(evolutionResponse)

Rysuje interaktywny wykres liniowy przedstawiający ewolucję populacji izotopów w czasie (na podstawie równań Batemana).

Wykorzystuje D3.js do wygenerowania wykresu ze skalą logarytmiczną na osi Y (aby uwidocznić populacje śladowe) oraz osią X wyrażoną w krotnościach czasu półtrwania izotopu matki. Zawiera interaktywną legendę, pozwalającą użytkownikowi na włączanie i wyłączanie widoczności poszczególnych izotopów na wykresie.

Argumenty:

• evolutionResponse (Object) – Obiekt JSON z danymi ewolucji pobranymi z backendu (zawiera flagę stabilności, czas półtrwania i dane historyczne).

Zwraca:

void – Funkcja modyfikuje bezpośrednio drzewo DOM.

drawSpectrumChart(spectra)

Generuje interaktywny wykres widma promieniowania jonizującego w formie wykresu igłowego (stem-and-bulb).

Używa D3.js do narysowania dyskretnych linii emisyjnych dla promieniowania alfa i gamma. Skala X (energia w keV) wykorzystuje transformację logarytmiczną w celu lepszej czytelności szerokich zakresów energii. Implementuje ukryte domyślnie etykiety narzędziowe (tooltipy), które pojawiają się po najechaniu kursorem na prążek widma, wyświetlając dokładną energię i wydajność rozpadu.

Argumenty:

• spectra (Object|null) – Obiekt z danymi widma pobrany z bazy danych lub wartość null, jeśli izotop nie posiada dyskretnych linii emisyjnych.

Zwraca:

void – Funkcja modyfikuje bezpośrednio drzewo DOM.