Autor: Miloš Halda
Bakalářská práce
Repo na GitHubu
Stránky projektu (GitHub pages)
Programátorská dokumentace (javadoc).
Obsah:
- PivotMoves
Tento program je určený pro testování potenciálových funkcí. Program využívá zjednodušený model proteinu (coarse-grained). Protein je zjednodušený na aminokyseliny reprezentované jako koule se středem v
Simulace probíhá ve 3 fázích, iniciace, běh a ukončení běhu.
Program přijme jako argumenty názvy simulací, (volitelně) cestu ke složce se vstupními soubory a (volitelně) cestu s výstupními soubory. Ze vstupního souboru načte parametry simulace:
- parametry pro výpočet LJ potenciálu,
- soubory s hodnotami bending a dihedrálního potenciálu,
FASTAsekvenci simulovaného proteinu,- počet cyklů simulace,
- frekvenci zaznamenávání dat simulace,
- a další, viz formát vstupního souboru.
Pomocí těchto veličin program vytvoří řetězec částic, který bude simulovat.
Program poté provede simulaci typu Pivot-Moves, což je postup kombinující přístup Monte-Carlo pro přijímání nových stavů a generování nových stavů pomocí pivotové transformace daného řetězce. Program provede zadaný počet cyklů, během kterých si ukládá důležité údaje ze simulace.
Uživatel má možnost si zvolit hodnoty potenciálů pro jednotlivé hodnoty úhlů/vzdáleností jednotlivých reprezentací aminokyselin. Definovat hodnoty potenciálů je nezbytné pro bending a dihedrální potenciál. Nevazebný potenciál má 2 možnosti. Buďto je zvolena možnost jej spočítat pomocí Lennard-Jonesovy funkce, viz bakalářská práce, sekce 2.3.1, nebo je zvolena možnost definovat hodnoty potenciálu v tabulce, podobně jako bending a dihedrální. Více viz ve specifikaci vstupních souborů a v tutoriálu.
Po provedení zadaného počtu cyklů program vyhodnotí relevantní průměry měřených veličin, zaznamená dobu běhu simulace a vypočítá errory. Vytvoří také výstupní (log) soubor s informacemi o simulaci.
Program se skládá z 10 tříd. Z programátorského hlediska jsou popsány blíž v technické dokumentaci (v EN). Představím je proto jen stručně z hlediska jejich použití v rámci programu.
- App
- hlavní třída s
main, volá ostatní funkce, - také jsou v ní uloženy některé metody pro zaznamenávání a postprocessing dat.
- obsahuje metodu ve které probíhá běh simulace (
pivotMovesSimulation)
- hlavní třída s
- Ball
- objekty této třídy reprezentují částice v simulaci.
- DataRange
- pomocná třída pro počítání errorů, reprezentuje úsek v datech.
- MyWatches
- objekty této třídy slouží pro měření času běhu simulace.
- MyWriter
- třída pro zapisování do souborů.
- Physics
- velmi důležitá třída, která implementuje "fyzikální engine" celé simulace.
- obsahuje metody pro výpočet potenciálů, síly, tlaku, vzdáleností a další.
- SimRunVars
- objekty této třídy slouží pro ukládání veličin důležitých pro konkrétní simulaci.
- SimSpace
- objekt této třítdy reprezentuje simulační prostor se všemi jeho veličinami, vstupy a výstupy.
- StepVars
- objekty této třídy slouží pro ukládání veličin důležitých pro každý konkrétní krok běhu simulace.
Další informace viz dokumentace programu (vygenerovaná pomocí javadoc).
Prakticky všechna data jsou většinu času uložena v textových souborech, kam se průběžně zapisují. V souborech jsou vstupní soubory (přípona .json, v případě tabulky s epsilony a potenciály přípona .csv), nezpracovaná data simulace (.csv), souřadnice molekul během simulace (.xyz), průměry veličin (.avg.csv) a výstupní soubor (.log), který obsahuje důležité údaje ze vstupu i z výsledků simulace (průměry, chyby a simulační čas). Ze vstupu jsou data uložena do proměnných a poté také jako parametry třídy Ball a především do objektu SimSpace. Objekt třídy SimSpace (v kódu zpravidla pojmenovaný jako s) hraje během simulace centrální roli, protože obsahuje všechny důležité parametry aktuálního stavu simulace a pomocí něj jsou tyto hodnoty předávány i metodám. Program má za účel simulaci libovolného množství molekul jednoho typu, které jsou reprezentovány objekty třídy Ball, v simulačním prostoru. Objekty třídy Ball jsou uloženy v objektu třídy ArrayList nazvaný balls a jsou atributem objektu s třídy SimSpace.
Ke spuštění programu je kromě Javy potřeba mít připravený vstupní soubor s parametry simulace a dále soubory, které jsou v něm definované.
Vstupní soubor má název ve formátu [název simulace].json. Složka se vstupním souborem je buďto složka, kde běží program, nebo může být explicitně definována pomocí možností -i a --input.
Celkově tedy vůči pracovnímu adresáři musí být na "path" ./[název vstupní složky][název simulace].json.
Vstupní soubor je ve formátu JSON a všechny položky uvedené v následujícím příkladu jsou nezbytné pro běh programu.
Uvedený příklad je okomentovanou verzí vzorového vstupního souboru.
(Pro použití ukázky níže je potřeba nejprve smazat řádky, které začínají znakem # kvůli validitě formátu JSON.)
Název souboru: 32Gly.in
{
# Typ simulace -- v této verzi programu je na výběr pouze jedna možnost.
"TypeOfSimulation": "Pivot-ChainMoves",
# Název matice pro AK specifické hodnoty `epsilon`:
"SimulationMatrixFileName": "AZ-Tanaka.csv",
# Název souboru s `FASTA` sekvencí simulovaného proteinu
"FASTAFileName": "32Gly.fasta",
# Poloměr kuliček. Nyní poloměr aminokyseliny:
"BallDiameter": 5,
# Počet cyklů simulace:
"NumberOfCycles": 40000,
# Počet cyklů pro ekvilibraci:
"NumberOfSkippedCycles": 20000,
Koeficient pro význam nevazebného potenciálu. Touto hodnotou je pronásobena hodnota nevazebného potenciálu během výpočtu potenciálu nového stavu. Jiné hodnoty než 1 jsou vhodné jen pro testování.
"EpsilonForNon-BondingPotential": 1,
# Parametr pro simulované žíhání. Počáteční teplota systému:
"Temperature-Init": 500,
# Parametr pro simulované žíhání. Hodnota teploty v posledním cyklu simulace. Hodnota teploty se mění v průběhu simulace lineárně.
"Temperature-Final": 300,
# Specifikovaný typ potenciálu, v současnosti jsou umožněny 2 možnosti:
# 1. "lennardjones" -> program počítá Lennard Jonesovu funkci,
# 2. "table" -> program využije tabulku s hodnotami potenciálů, která je specifikovaná v položce "NonBondingPotentialTableName".
"TypeOfNonBondingPotential": "lennardjones",
# Pokud je v položce "TypeOfNonBondingPotential" hodnota "table", je nutné v této položce uvést název souboru s nevazebným potenciálem.
"NonBondingPotentialTableName": null,
# Název souboru s bending potenciálem:
"BendingPotentialTableName": "bendingPotential.csv",
# Název souboru s dihedrálním potenciálem:
"DihedralPotentialTableName": "dihedralPotential.csv",
# Rozsah ve kterém bude náhodně vybírán úhel pro otočení během návrhu nového stavu:
"RotationRange": 0.5,
# Délka vazby mezi aminokyselinami (vzdálenost $C_\alpha$-$C_\alpha$)
"LengthOfBond": 3.81,
# Frekvence zápisu souřadnic aminokyselin do `.xyz` souboru:
"XYZFreq": 100,
# Frakvence zápisu dat do `.csv` souboru:
"DATAFreq": 100,
# Konfigurace pro vytváření `tcl` skriptu. V případě hodnoty `true` bude stav proteinu v posledním cyklu ve VMD rovnou vyrenderován.
"RenderTCL": false
}Soubor pro epsilony specifickými pro jednotlivé kombinace aminokyselin (jeho název je specifikován ve vstupním JSON souboru v položce "SimulationMatrixFileName") má následující formát:
[řádek se značkami typů aminokyselin (musí se shodovat se značkami pro aminokyseliny v souboru `FASTA`)]
[Matice $N×N$, kde $N$ označuje počet aminokyselin na prvním řádku]
[Pozice v (i+1)-tém řádku a j-tém sloupci odpovídá kombinaci i-té a j-té aminokyseliny na prvním řádku]Jednodušší ale bude nejspíš ukázat příklady reálně používaných souborů.
Pro jednoduchost nejprve matice $2×2$ pro tzv. HP model (rozlišuje se jen na hydrofóbní a hydrofilní aminokyseliny):
H,P
2,8
8,1 Během testování programu byla využita matice upravená z Tanaky 1976 (upravená tabulka III., více v Bakalářce). Protože se jedná o rozsáhlejší soubor, není zde vložena kvůli přehlednosti. Je možné ji najít ve vzorové složce pro vstupní soubory.
Hodnoty "epsilon" jsou při výpočtu nevazebného potenciálu zohledněny jen pokud je využita možnost výpočtu pomocí Lennard Jonesovy funkce. Při využití tabulky s předpočítanými hodnotami se "epsilon" nezohledňuje.
Soubory specifikované ve vstupním JSON souboru jako položky
"BendingPotentialTableName" a
"DihedralPotentialTableName" obsahují hodnoty potenciálů pro dané hodnoty úhlů.
Speciálním případem je nevazebný potenciál. Pokud je ve vstupním souboru v položce "TypeOfNonBondingPotential" zvolena možnost "lennardjones", program automaticky počítá s funkcí Lennard Jonesova potenciálu, jak byla specifikována v kapitole Běh. Pokud je zvolena možnost "table", je potřeba ještě specifikovat soubor pro hodnoty nevazebného potenciálu v položce "NonBondingPotentialTableName". V tutoriálu je ukázáno, jak tuto moznost využít.
Při vytváření těchto souborů je potřeba mít na paměti, že bending potenciál je definován v intervalu
Samotné soubory mají následující formát:
phi,U
[hodnoty úhlu],[hodnoty potenciálu]V sloupci "phi" jsou hodnoty úhlu a ve sloupci "U" jsou hodnoty potenciálu pro tyto úhly, hodnoty jsou oddělené , (protože se jedná o CSV soubory). Při simulaci je vždy vybrána hodnota potenciálu, jejíž úhel je nejblíže hodnotě úhlu v simulaci.
Pro ukázku uvedu prvních deset hodnot ze souboru dihedralPotential.csv, který byl použit při testování:
phi,U
-3.1060060391703654,-8.59711281459211
-3.070401971458418,-8.63817111796914
-3.0347979037464703,-8.722580021141189
-2.9991938360345225,-8.783855896643942
-2.963589768322575,-8.805824812903607
-2.9279857006106274,-8.86120833720818
-2.8923816328986796,-8.882946799288174
-2.856777565186732,-8.875287128108384
-2.8211734974747844,-8.851233902846035
-2.7855694297628366,-8.847503625923641Soubor pro nevazebný potenciál má stejný formát, jen místo úhlu phi je v prvním sloupci uvedena hodnota vzdálenosti dvou kuliček (r [Å]).
Celé soubory LJPotential.csv, dihedralPotential.csv a bendingPotential.csv jsou ve vzorové složce vstupů (/input/vzory/).
Soubor FASTA (položka "FASTAFileName" ve vstupním JSON souboru) obsahuje vstupní sekvenci aminokyselin. Je potřeba zkontrolovat, aby všechny uvedené značky aminokyselin byly také v headeru tabulky pro AK specifické hodnoty epsilon.
Soubor má formát jako klasický FASTA soubor, jen není podstatný první řádek s informacemi o sekvenci:
[řádek s informacemi o sekvenci, důležité pro uživatele, program je ignoruje]
[sekvence aminokyselin]
Jako příklad uvedu soubor s 32 glyciny v sekvenci:
>polygly32
GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG
či se všemi aminokyselinami:
>all-AKs
ARNDCQEGHILKMFPSTWYV
V případě, že je použita možnost --restore musí být ve vstupní složce i XYZ soubor, ze kterého budou "obnoveny" pozice aminokyselin v daném kroce simulace.
Cesta ke vstupnímu souboru se počítá od vstupní složky:
[vstupní složka][název souboru]Tento soubor obsahuje pouze jeden "frame" (doporučená varianta), v případě, že obsahuje více "framů" bude vybrán automaticky ten první v souboru.
Počet aminokyselin pro strukturu v XYZ souboru se musí shodovat s počtem aminokyselin ve vstupní FASTA sekvenci.
Formát souboru vypadá takto:
[počet molekul (integer), musí se shodovat s počtem AK viz řádek 3 a další]
[informace o tom, ve kterém kroku byla daná konfigurace AK]
[3 a další řádky jsou aminokyseliny a jejich souřadnice.]
[Kód aminokyseliny] [souřadnice x] [souřadnice y] [souřadnice z]
Ukázkový restore soubor soubor je ve složce příkladů.
Obecně se program spustí příkazem:
java -jar molecularjava.jar [možnosti] [název simulace 1] [název simulace 2] ...kde možnosti jsou tyto:
-i, --input # Explicitně daná složka se vstupními soubory.
-o, --output # Explicitně daná složka s výstupními soubory.
-h, --help # Odkáže na tento návod.
--restore [xyz soubor pro obnovení stavu simulace] # volitelný Pro příklad vstupního souboru z předchozího odstavce by příkaz vypadal takto (příaz bude fungovat pouze pokud jsou připraveny vstupní soubory ve složce input/, je vytvořena složka data/ a jsme ve složce PivotMovesSimulation):
java -jar PMSimulation/PMSimulation.jar -i input/ -o data/ 32GlyKaždý 10000 krok program vypíše, v jakém cyklu právě je a na konci program vypíše Simulation [název zadané simulace] Was succesfull.. Tento výstup byl vložen kvůli lepší kontrole uživatele nad průběhem simulace. Výstup je samozřejmě možné přesměrovat do nulového výstupu:
Pro Linux:
java -jar PMSimulation/PMSimulation.jar -i input/ -o data/ 32Gly > /dev/nullPro Windows:
java -jar PMSimulation/PMSimulation.jar -i input\ -o data\ 32Gly > NULLVýstupní soubory je pak možné najít ve složce, kde běží program, nebo ve složce, kterou jsme si explicitně definovali.
Jejich název je prakticky stejný jako název vstupního souboru jen s jinými příponami. Pro naší simulaci bychom našli tyto soubory:
[název simulace].avg.csv # Obsahuje průměry.
[název simulace].csv # Obsahuje data ze simulace.
[název simulace].log # Výstupní soubor.
[název simulace].xyz # Soubor souřadnic molekul v prostoru. Je možné je zobrazit např. v programu VMD.Pro výsledky vizte kapitolu 5 Výsledky v bakalářské práci.
Pro zobrazení simulace v programu VMD (Visual Molecular Dynamics) slouží simulací vygenerované soubory XYZ a TCL
Použijte příkaz ve tvaru:
vmd -f [výstupní složka][název simulace].xyz -e [výstupní složka][název simulace].tclBarvy kuliček odpovídají barevnému kódu jak je uveden v bakalářské práci v kapitole 3 Výsledky.
Pokud byla nastavena položka "RenderTCL" ve vstupním JSON souboru na true, VMD se zapne, vytvoří snapshot struktury a vypne se. Tomu je možné zabránit odstraněním příkazů, které následující po řádku
#RENDERINGPro více informací je možné zadat vmd --help do příkazové řádky, nebo se podívat na stránky VMD.
Pro lepší pochopení je možné si přímo program vyzkoušet. Tutoriál je připravený pro uživatele Linuxu, při splnění prerekvizit s malými modifikacemi (např. lomítko \ namísto /) tutoriál funguje také pro uživatele Windows, případně Mac OS.
- stažené repository z GitHubu na počítač
- instalovaná Java 8 nebo novější
- instalované VMD (pro zobrazení hotového proteinu)
Pokud jsme s příkazovou řádkou v hlavní složce projektu (PivotMovesSimulation), můžeme se podívat do složky input/vzory/ pomocí příkazu
ls -l input/vzory/Zde jsou připravené vstupní soubory pro simulaci:
priklad.jsonall-aks.fastabendingPotential.csvdihedralPotential.csvpriklad-restore.xyz- ten využijeme až při další fázi tutoriálu.
a další soubory, které se mohou hodit např. při simulaci HP modelu.
Pro vyčištění složky data před tutoriálem je možné spustit příkaz
rm -ri data/* # možnost 'i' je přidána kvůli bezpečnosti příkazu...Dále je potřeba vytvořit složku na výstupy programu, např. příkazem
mkdir data/prikladProgram se nyní spustí pomocí příkazu:
java -jar PMSimulation/PMSimulation.jar -i input/vzory/ -o data/priklad/ prikladNa výstupu se zobrazí postupně toto:
10000/40000 (25%)
20000/40000 (50%)
30000/40000 (75%)
40000/40000 (100%)
Simulation priklad: Was succesfull.Nyní ve výstupní složce uvidíme
(např. pomocí příkazu)
ls -l data/prikladvytvořené tyto soubory:
priklad.avg.csvpriklad.csvpriklad.logpriklad.tclpriklad.xyz
Význam těchto souborů viz sekce Vstupní soubory.
Pro využítí možnosti obnovy určitého stavu simulace je potřeba nejprve vytvořit soubor priklad-retore.xyz, např. příkazem
touch input/vzory/priklad-restore.xyz # Tento příkaz je bezpečný a nijak nezmění obsah souboru, pokud již existuje.Nyní do něj vložíme jeden kompletní frame ze souboru data/priklad/priklad.xyz. Od tohoto framu se bude simulovat. Funkční soubor jsem již vytvořil během psaní tohoto tutoriálu, takže můžete rovnou použít ten již existující.
Program bude po spuštění fungovat stejně jako při prvním běhu, jen pozor, aby se nám nesmazala data z prvního běhu, je potřeba výstup přesměrovat do jiné složky!
mkdir data/restore
Samozřejmě můžeme i upravit vstupní JSON soubor (např. nastavit jen doplňkový počet kroků).
Nyní už můžeme program spustit:
java -jar PMSimulation/PMSimulation.jar -i input/vzory/ -o data/restore/ --restore priklad-restore.xyz priklad
Output se při tomto běhu neliší od původního běhu.
Stejně tak i výstupní soubory zůstaly stejné.
Nyní můžeme výsledky naší simulace zobrazit. Toho dosáhneme buďto klikáním v grafickém interfacu VMD, nebo přímo z příkazové řádky:
vmd -f data/restore/priklad.xyz -e data/restore/priklad.tclPokud nechceme počítat nevazebný potenciál přímo jako Lennard-Jonesův potenciál, je možné ve vstupním souboru definovat tabulku s hodnotami potenciálu.
Ve složce input/vzory je předpřipravený vstupní soubor priklad-LJ-tabulka.json, který s touto možností počítá.
V tomto souboru si všimněme změn ve 2 položkách oproti původnímu priklad.json:
"TypeOfNonBondingPotential": "table",
"NonBondingPotentialTableName": "LJPotential.csv",V položce "NonBondingPotentialTableName" (v souboru LJPotential.csv) je definována tabulka s předpočítanými hodnotami nevazebného potenciálu. Pro tento příklad jsem zvolil Lennard Jonesův potenciál s cutoffem v hodnotách 4Å a 15Å. Uživatel si může samozřejmě tyto hodnoty upravit, jak potřebuje.
Spuštění programu proběhne stejně, jako v prvním případě:
java -jar PMSimulation/PMSimulation.jar -i input/vzory/ -o data/priklad/ priklad-LJ-tabulkaVidíme, že po doběhnutí simulace se vytvořili ve výstupní složce (data/priklad/) standardní výstupní soubory.
POZOR!
Při vytváření souboru s hodnotami nevazebného potenciálu je potřeba počítat s tím, že nebudou využity hodnoty AK-specifických epsilonů, jak jsou definované v jejich tabulce. Epsilon je standardně zvolen jako hodnota v položce "EpsilonForNon-BondingPotential" vstupního souboru.
(A jejich řešení. Zatím jen jeden, dělám sbírku.)
Při použítí programu se vám může snadno stát to, co mě a zapomenete při spuštění simulace dát při možnosti vstupní/výstupní složky na konec znak /.
Takovýto chybný příkaz vypadá např. takto:
java -jar PMSimulation/PMSimulation.jar -i input/vzory -o data/priklad/ prikladVýstupem bude chybová hláška:
Exception in thread "main" java.io.FileNotFoundException: input/vzorypriklad.json (No such file or directory)
at java.base/java.io.FileInputStream.open0(Native Method)
at java.base/java.io.FileInputStream.open(FileInputStream.java:216)
at java.base/java.io.FileInputStream.<init>(FileInputStream.java:157)
at java.base/java.io.FileInputStream.<init>(FileInputStream.java:111)
at java.base/java.io.FileReader.<init>(FileReader.java:60)
at com.molecular_java.SimSpace.<init>(SimSpace.java:194)
at com.molecular_java.App.main(App.java:545)Pro opravení stačí lomítko přidat:
java -jar PMSimulation/PMSimulation.jar -i input/vzory/ -o data/priklad/ prikladV případě, že v tomto README naleznete chybu mě prosím kontaktujte přes můj GitHub účet! Děkuji!