Post on 10-Jul-2020
RMGStudyGroupSessionI:Git,Sphinx,webRMG
ConnieGao9/20/2013
1
WhytheRMGStudyGroup?
§ DevotedtoRMG-Py§ HelpnewuserslearnhowtosetupRMG§ Existingusersanddeveloperscandiscussspecificsincode
§ RMG-Py documentationgetswrittenbeforeeachsession!(excepttoday’ssession)
2
Today’sTopics
§ Git:theversioncontroltoolforRMG§ Sphinx:toolforcreatingdocumentation§ webRMG:onlinetoolsforworkingwithRMG
3
KeyURLs
§ http://www.github.com/GreenGroup§ Git repositoryofallRMG-Py code
§ http://greengroup.github.io/RMG-Py/§ OnlineversionofthecurrentRMG-Py documentation
§ http://rmg.mit.edu§ OfficialRMG-Py documentation,thermodynamicsandkineticsdatabasebrowser,andwebtools
§ http://dev.rmg.mit.edu§ Developmentalversionofrmg.mit.edu withlatestfeaturesandpotentialbugs
§ Touse,add18.172.0.124 dev.rmg.mit.edu tohostsfileinyouroperatingsystem
4
Git5
Git
§ Git isaversioncontroltool§ Multipleuserscaneditmultiplecopiesofcode§ Singleusercancreatemultiplebranchesforasinglerespository
§ Onlinedetailedtutorial:§ http://git-scm.com/book
§ Wheretofindprogramstohelpyouusegit:§ http://git-scm.com/downloads
6
BasicGit Workflow
1. Modify filesinyourworkingdirectory.2. Stage files,addingsnapshotsofthemto
yourstagingarea.3. Makeacommit,whichtakesthefilesas
theyareinthestagingareaandstoresthatsnapshotpermanentlytoyourGit directory.
7
Git filelifecycle
Notes:Ifaparticularversionofafileisinthegit directory,it’sconsideredcommitted.Ifit’smodifiedbuthasbeenaddedtothestagingarea,itisstaged.Ifitwaschanged sinceitwascheckedoutbuthasnot beenstaged,itismodified.
8
Gettingstarted:createalocalrepo
Twocommonscenarios:(onlydooneofthese)a) Tocloneanalreadyexistingrepotoyourcurrent
directory:$ git clone <url> [local dir name]Thiswillcreateadirectorynamedlocaldir name,containingaworkingcopyofthefilesfromtherepo,anda.git directory(usedtoholdthestagingareaandyouractualrepo)
b) TocreateaGit repoinyourcurrentdirectory:$ git initThiswillcreatea.git directoryinyourcurrentdirectory.Thenyoucancommitfilesinthatdirectoryintotherepo:$ git add file1.java$ git commit –m “initial project version”
9
CommonGit commands
10
YoucandoallofthisusingGit-cola:apowerfulGUIinterface
Commitorrevertspecificlines.Stagefilesandwritecommitmessagesgraphically.Amendcommits.
11
Git-cola:apowerfulGUInterface
Visualizepastcommithistoryandrepositorybranches.(Greatfortrackingspecificcodechanges.)
AvailableforWindows,Mac,andLinux!
12
Stepsforgettingstartedwithgit andRMG-Py
1. Clone theRMG-Py git repositoryontoyourlocaldirectory(orontoaserversuchasPharoswhichhasalltheRMG-Pydependenciesaswellasgit preinstalled)
2. Aftermakingchangestocode,testtoensurenothingisbroken
3. Rungit pullofficialmastertopullinlatestofficialcommits4. Stage yourmodifiedfilesandmakeacommit ofyour
changes,withausefulcommitmessage5. Push thecommittoyourgithub repository
Note:PostissuesandbugsinthecodetotheRMG-Py issuespageongithub sootherscanhelpyouaddressyourproblemhttps://github.com/GreenGroup/RMG-Py/issues
13
14
Sphinx
§ Toolforcreatingintelligent andbeautifuldocumentation
§ OutputformatsinbothHTMLandLaTeX PDF§ UsesreStructuredText asitsmarkuplanguage
15
RMG-Py documentation
§ LocatedinRMG-Py/documentationfolder§ Howtobuild:
§ Run‘makedocumentation’inparentRMG-PyfolderwillbuildtheHTMLpages
§ Or,gotodocumentationfolderandrun‘makehtml’tomakeHTMLpagesor‘makelatexpdf’tocreatethepdf versionofthedocumentation
§ Editthefilesinsidethedocumentation/sourcefolder
16
reStructuredText Basics§ PrimerforreS:
§ http://sphinx-doc.org/rest.html#rst-primer§ ExampleofSphinxmarkup:
17
ExamplemarkupconvertedtoHTML:
18
Usingpythonfunctionreferencesindocumentation
§ FunctioncommentscanbeimportedtoSphinxdocumentationautomatically
19
ORIGINAL CODERMG-Py/rmgpy/statmech/vibration.pyx
20
DOCUMENTATION SOURCERMG-Py/documentation/source/reference/statmech/harmonicoscillator.rst
Thislinepullsoriginalfunctiondocstring intodocumentationautomatically
…butyoucanappendonmoreinformationorequationsthanthedocstring bywritingadditionaldocumentationhere
21
DOCUMENTATION HTML PAGERMG-Py/documentation/build/html/reference/statmech/harmonicoscillator.rst
Thispagehasthecombinedpythondocstring informationaswellastheextradocumentationyouadded
NOTE:Theofficialgithub documentationpagesforRMG-Py automaticallyupdatewhenchangesaremadetothecodedocstrings,soyoudon’thavetodoanyextrawork
StepsforwritingRMG-Py documentation
1. Createandeditnewdocumentationpages(.rstfiles)locally.Usecodereferenceswhereappropriatetosavetime.
2. Buildhtmlpageslocallytopreviewthatthepagesaresatisfactoryinlayout.
3. Usegit tocommit thesource.rst filesthatyoumodifiedtotheRMG-Py github repository.
4. Youaredone!OfficialRMG-Py documentationpageswillbeupdatedautomatically.
22
23
webRMG
webRMG
§ URLs:§ Officialversion:http://rmg.mit.edu§ Development(newer)version:http://dev.rmg.mit.edu
§ MakeRMG’sdatabasesmoretransparent,accessible,andmodifiable
§ Webtoolsforvisualizingkineticsandreactionsmoreeasily
§ BuiltonaDjango pythonframeworkwhichqueriestheRMG-Py codeitself!
24
Features
25
§ Editingoraddingnewratesorthermodatatothedatabase§ Editsourceonlinewithaccount§ Changesmakeanautomaticcommitongithub
§ CommitgetsreviewedbyGreenGroupmembersbeforebeingpublishedtoofficial
§ ExportdatabaseforRMG-Java§ ConvertsRMG-Py databasetoRMG-Javadatabaseformat
§ Exportscurrentversionofdatabaseonwebsitein.zipor.tar.gzformat
26
§ UseanyidentifierandconvertittoanadjacencylistusedinRMG§ SMILES§ InChI§ Commonchemicalnames
§ Previewmoleculewhileeditingadjacencylist§ Viewmoleculedata:
§ Molecularweight,identifiers,thermo
27
§ ComparekineticsinmodelwithkineticsfoundinRMG’sdatabases§ Displaysmatchingreactionlibraryresults,rateestimatesfromRMG-JavaandRMG-Py,identifiesraterulecontributions,linkstosources
§ ToolbarforsearchingNISTdatabaseautomaticallyfillsinreactantandproductfields
§ CompareratesatagivenT
28
§ Modelvisualization(RMG-Py andJavafriendly)§ VisualizeamodelgeneratedfromRMGusingitschemkin fileandRMGdictionaryonHTMLpage
§ ClickinganyreactionlinksearchesRMGdatabaseforreactionkinetics
§ Clickingonanymolecule’simagegivesadditionalinfoandlinktothermochemistry
§ Modelcomparison(RMG-Py andJavafriendly)§ Comparetwomodelsagainsteachother§ Identifycommonvs.uniquespeciesandreactions§ Identifysimilaritiesordifferencesinthermoandkinetics
29
§ Fluxdiagramgeneration(RMG-Py andJavafriendly)§ CreatevideoofareactionnetworkusingRMGconditionfile,chemkin file,andRMGdictionary
§ Canoptionallyusechemkin outputfileforanon-isothermalsimulation(maycurrentlybebroken)
§ PopulateReactions(RMG-Py only)§ Generatealistofallreactionsoccurringgivenasetofinitialspecieslistedinaconditionfile(producesthesetofedgereactionsinasimulation)
30
§ Plotforwardandreversekinetics(RMG-Py andJavafriendly)§ Usechemkin fileandRMGdictionary(optional)togenerateplotsofforwardandreversereactionkinetics
§ CreateRMG-JavaKineticsLibrary§ Convertachemkin fileandRMGdictionaryintoaRMG-Javakineticslibrary
§ Mergemodels§ Generatemergedchemkin fileandRMGdictionaryfor2models
31
§ CreateInputFile(RMG-Py only)(maycurrentlybebroken)§ UsewebformtogenerateinputfileforaRMGjobormodifyanexistinginputfile
§ Moreuserfriendlyandlesserrorpronethanworkingwithsourcecode
§ Providesfilled-invaluesasrecommendationsforadvancedoptionsintheinputfile
32