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