From 7fa53f518ab7878eb7be1647cdb13b9984893ec5 Mon Sep 17 00:00:00 2001 From: Ryan Kingsbury Date: Thu, 18 Jul 2024 11:09:32 -0400 Subject: [PATCH] Docs: add Document Models / emmet tutorial (#917) * Docs: add schema tutorial * lnt --- docs/_static/docs_store_Si_relax.json | 1 + docs/index.md | 1 + docs/user/docs_schemas_emmet.md | 506 ++++++++++++++++++++++++++ docs/user/install.md | 2 + docs/user/running-workflows.md | 1 + 5 files changed, 511 insertions(+) create mode 100644 docs/_static/docs_store_Si_relax.json create mode 100644 docs/user/docs_schemas_emmet.md diff --git a/docs/_static/docs_store_Si_relax.json b/docs/_static/docs_store_Si_relax.json new file mode 100644 index 0000000000..8f54f2f0bb --- /dev/null +++ b/docs/_static/docs_store_Si_relax.json @@ -0,0 +1 @@ +[{"uuid":"c2b5eb7d-838b-4dee-896f-95f21867b62b","index":1,"output":{"builder_meta":{"emmet_version":"0.83.0","pymatgen_version":"2024.4.13","pull_request":null,"database_version":null,"build_date":"2024-05-19T21:13:45.541000","license":null},"nsites":2,"elements":["Si"],"nelements":1,"composition":{"Si":2.0},"composition_reduced":{"Si":1.0},"formula_pretty":"Si","formula_anonymous":"A","chemsys":"Si","volume":40.163300666862035,"density":2.3223723738160613,"density_atomic":20.081650333431018,"symmetry":{"crystal_system":"Cubic","symbol":"Fd-3m","number":227,"point_group":"m-3m","symprec":0.1,"version":"2.4.0"},"tags":null,"dir_name":"della-r3c1n3:/scratch/gpfs/ab6989/MPScanRelaxSet/atomate2/Ca_Mg_runs/job_2024-05-19-21-13-15-058677-64911","state":"successful","calcs_reversed":[{"dir_name":"/scratch/gpfs/ab6989/MPScanRelaxSet/atomate2/Ca_Mg_runs/job_2024-05-19-21-13-15-058677-64911","vasp_version":"6.4.2","has_vasp_completed":"successful","input":{"incar":{"PREC":"Accurate","ALGO":"Fast","ISPIN":2,"NELM":200,"IBRION":2,"EDIFF":0.00001,"EDIFFG":-0.02,"NSW":99,"ISIF":3,"ENCUT":680.0,"ENAUG":1360.0,"MAGMOM":[0.6,0.6],"LREAL":false,"ISMEAR":0,"SIGMA":0.2,"LWAVE":false,"LCHARG":false,"LVTOT":false,"LORBIT":11,"LELF":false,"LASPH":true,"LAECHG":true,"GGA":"Ps","LMIXTAU":true},"kpoints":{"comment":"Kpoints from vasprun.xml","nkpoints":0,"generation_style":"Gamma","kpoints":[[7,7,7]],"usershift":[0.0,0.0,0.0],"kpts_weights":null,"coord_type":null,"labels":null,"tet_number":0,"tet_weight":0,"tet_connections":null,"@module":"pymatgen.io.vasp.inputs","@class":"Kpoints"},"nkpoints":20,"potcar":["PAW_PBE"],"potcar_spec":[{"titel":"PAW_PBE Si 05Jan2001","hash":"c27340a9c98542122fbad458bbb5d441","summary_stats":{"keywords":{"header":["dexc","eatom","eaug","enmax","enmin","icore","iunscr","lcor","lexch","lpaw","lultra","ndata","orbitaldescriptions","orbitals","pomass","raug","rcore","rdep","rdept","rmax","rpacor","rrkj","rwigs","step","titel","vrhfin","zval","nentries"],"data":["localpart","gradientcorrectionsusedforxc","corecharge-density(partial)","kineticenergydensity(partial)","atomicpseudocharge-density","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","pawradialsets","(5e20.12)","augmentationcharges(nonsperical)","uccopanciesinatom","grid","aepotential","corecharge-density","kineticenergy-density","mkineticenergy-densitypseudized","localpseudopotentialcore","pspotentialvalenceonly","corecharge-density(pseudized)","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","endofdataset"]},"stats":{"header":{"MEAN":9.198469218699186,"ABSMEAN":9.198469218699186,"VAR":1790.7147656424072,"MIN":0.0,"MAX":322.069},"data":{"MEAN":215.16613596661992,"ABSMEAN":237.9507629282115,"VAR":3381771.445249609,"MIN":-872.57185,"MAX":24929.6947974}}}}],"potcar_type":["PAW_PBE"],"parameters":{"SYSTEM":"unknown system","LCOMPAT":false,"PREC":"accura","ENMAX":680.0,"ENAUG":1360.0,"EDIFF":0.00001,"IALGO":68,"IWAVPR":11,"NBANDS":40,"NBANDSLOW":-1,"NBANDSHIGH":-1,"NELECT":8.0,"TURBO":0,"IRESTART":0,"NREBOOT":0,"NMIN":0,"EREF":0.0,"ISMEAR":0,"SIGMA":0.2,"KSPACING":0.5,"KGAMMA":true,"KBLOWUP":true,"LREAL":false,"ROPT":[0.0],"LMAXPAW":-100,"LMAXMIX":2,"NLSPLINE":false,"ISTART":0,"ICHARG":2,"INIWAV":1,"ISPIN":2,"LNONCOLLINEAR":false,"MAGMOM":[0.6,0.6],"NUPDOWN":-1.0,"LSORBIT":false,"SAXIS":[0.0,0.0,1.0],"LSPIRAL":false,"QSPIRAL":[0.0,0.0,0.0],"LZEROZ":false,"LASPH":true,"LMETAGGA":false,"NELM":200,"NELMDL":-5,"NELMIN":2,"ENINI":680.0,"LDIAG":true,"LSUBROT":false,"WEIMIN":0.001,"EBREAK":6e-8,"DEPER":0.3,"NRMM":4,"TIME":0.4,"AMIX":0.4,"BMIX":1.0,"AMIN":0.1,"AMIX_MAG":1.6,"BMIX_MAG":1.0,"IMIX":4,"MIXFIRST":false,"MAXMIX":-45,"WC":100.0,"INIMIX":1,"MIXPRE":1,"MREMOVE":5,"LDIPOL":false,"LMONO":false,"IDIPOL":0,"EPSILON":1.0,"DIPOL":[-100.0,-100.0,-100.0],"EFIELD":0.0,"NGX":36,"NGY":36,"NGZ":36,"NGXF":72,"NGYF":72,"NGZF":72,"ADDGRID":false,"NSW":99,"IBRION":2,"MDALGO":0,"ISIF":3,"PSTRESS":0.0,"EDIFFG":-0.02,"NFREE":1,"POTIM":0.5,"SMASS":-3.0,"SCALEE":1.0,"TEBEG":0.0001,"TEEND":0.0001,"NBLOCK":1,"KBLOCK":99,"NPACO":256,"APACO":10.0,"ISYM":2,"SYMPREC":0.00001,"LORBIT":11,"RWIGS":[-1.0],"NEDOS":301,"EMIN":10.0,"EMAX":-10.0,"EFERMI":0.0,"NWRITE":2,"LWAVE":false,"LDOWNSAMPLE":false,"LCHARG":false,"LPARD":false,"LVTOT":false,"LVHAR":false,"LELF":false,"LOPTICS":false,"STM":[0.0,0.0,0.0,0.0,0.0,0.0,0.0],"NPAR":40,"NSIM":4,"NBLK":-1,"LPLANE":true,"LSCALAPACK":true,"LSCAAWARE":false,"LSCALU":false,"LASYNC":false,"LORBITALREAL":false,"IDIOT":3,"PHON_NSTRUCT":-1,"LMUSIC":false,"POMASS":[28.085],"DARWINR":[0.0],"DARWINV":[1.0],"LCORR":true,"GGA_COMPAT":true,"LBERRY":false,"ICORELEVEL":0,"LDAU":false,"I_CONSTRAINED_M":0,"GGA":"PS","VOSKOWN":0,"LHFCALC":false,"PRECFOCK":"","LSYMGRAD":false,"LHFONE":false,"LRHFCALC":false,"LTHOMAS":false,"LMODELHF":false,"LFOCKACE":false,"ENCUT4O":-1.0,"EXXOEP":0,"FOURORBIT":0,"AEXX":0.0,"HFALPHA":0.0,"MCALPHA":0.0,"ALDAX":1.0,"AGGAX":1.0,"ALDAC":1.0,"AGGAC":1.0,"NKREDX":1,"NKREDY":1,"NKREDZ":1,"SHIFTRED":false,"ODDONLY":false,"EVENONLY":false,"LMAXFOCK":0,"NMAXFOCKAE":0,"LFOCKAEDFT":false,"HFSCREEN":0.0,"HFSCREENC":0.0,"NBANDSGWLOW":0,"LUSE_VDW":false,"IVDW_NL":1,"LSPIN_VDW":false,"Zab_VDW":-0.8491,"PARAM1":0.1234,"PARAM2":1.0,"PARAM3":0.0,"MODEL_GW":0,"MODEL_EPS0":12.2078502,"MODEL_ALPHA":1.0,"LEPSILON":false,"LRPA":false,"LNABLA":false,"LVEL":false,"CSHIFT":0.1,"OMEGAMAX":-1.0,"DEG_THRESHOLD":0.002,"RTIME":-0.1,"WPLASMAI":0.0,"DFIELD":[0.0,0.0,0.0],"WPLASMA":[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0],"NUCIND":false,"MAGPOS":[0.0,0.0,0.0],"LNICSALL":true,"ORBITALMAG":false,"LMAGBLOCH":false,"LCHIMAG":false,"LGAUGE":true,"MAGATOM":0,"MAGDIPOL":[0.0,0.0,0.0],"AVECCONST":[0.0,0.0,0.0],"LALL_IN_ONE":false,"IALL_IN_ONE":-1,"NBANDS_WAVE":-1,"LFINITE_TEMPERATURE":false,"LADDER":false,"LRPAFORCE":false,"LFXC":false,"LHARTREE":true,"IBSE":0,"KPOINT":[-1,0,0,0],"LTCTC":false,"LTCTE":false,"LTETE":false,"LTRIPLET":false,"LFXCEPS":false,"LFXHEG":false,"NATURALO":2,"LHOLEGF":false,"L2ORDER":false,"LDMP1":false,"LMP2LT":false,"LSMP2LT":false,"LGWLF":false,"ENCUTGW":-1.60000002,"ENCUTGWSOFT":-1.60000002,"ENCUTLF":-1.0,"LESF_SPLINES":false,"LMAXMP2":-1,"SCISSOR":0.0,"NOMEGA":0,"NOMEGAR":0,"NBANDSGW":-1,"NBANDSO":-1,"NBANDSV":-1,"NELMGW":1,"NELMHF":1,"DIM":3,"IESPILON":4,"ANTIRES":0,"OMEGAMIN":-30.0,"OMEGATL":-200.0,"OMEGAGRID":0,"LSELFENERGY":false,"LSPECTRAL":false,"LSPECTRALGW":false,"LSINGLES":false,"LFERMIGW":false,"ODDONLYGW":false,"EVENONLYGW":false,"NKREDLFX":1,"NKREDLFY":1,"NKREDLFZ":1,"MAXMEM":2800,"TELESCOPE":0,"NTAUPAR":-1,"NOMEGAPAR":-1,"DAMP_NEWTON":0.80000001,"LAMBDA":1.0,"OFIELD_KAPPA":0.0,"OFIELD_K":[0.0,0.0,0.0],"OFIELD_Q6_NEAR":0.0,"OFIELD_Q6_FAR":0.0,"OFIELD_A":0.0,"KPOINTS_OPT_MODE":1,"LKPOINTS_OPT":false},"lattice_rec":{"@module":"pymatgen.core.lattice","@class":"Lattice","matrix":[[-1.150766539776481,1.150766539776481,1.150766539776481],[1.150766539776481,-1.150766539776481,1.150766539776481],[1.150766539776481,1.150766539776481,-1.1507665397764812]],"pbc":[true,true,true]},"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[0.0,2.73,2.73],[2.73,0.0,2.73],[2.73,2.73,0.0]],"pbc":[true,true,true],"a":3.8608030252785492,"b":3.8608030252785492,"c":3.8608030252785492,"alpha":59.99999999999999,"beta":59.99999999999999,"gamma":59.99999999999999,"volume":40.692834},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.0,0.0],"xyz":[0.0,0.0,0.0],"properties":{},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.365,1.365,1.365],"properties":{},"label":"Si"}]},"is_hubbard":false,"hubbards":{}},"output":{"energy":-11.48288783,"energy_per_atom":-5.741443915,"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[-0.0,2.7181064862403606,2.7181064862403606],[2.7181064862403606,0.0,2.7181064862403606],[2.7181064862403606,2.7181064862403606,0.0]],"pbc":[true,true,true],"a":3.8439830568153965,"b":3.8439830568153965,"c":3.8439830568153965,"alpha":60.00000000000001,"beta":60.00000000000001,"gamma":60.00000000000001,"volume":40.163300666862035},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[-0.0,-0.0,-0.0],"xyz":[0.0,0.0,0.0],"properties":{"magmom":-0.0},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.3590532431201803,1.3590532431201803,1.3590532431201803],"properties":{"magmom":-0.0},"label":"Si"}]},"efermi":5.96853235,"is_metal":false,"bandgap":0.45999999999999996,"cbm":6.2225,"vbm":5.7625,"is_gap_direct":false,"direct_gap":2.5146000000000006,"transition":"(0.000,0.000,0.000)-(0.429,0.429,-0.000)","mag_density":-1.2698159551931228e-7,"epsilon_static":null,"epsilon_static_wolfe":null,"epsilon_ionic":null,"frequency_dependent_dielectric":{"real":null,"imaginary":null,"energy":null},"ionic_steps":[{"e_fr_energy":-11.48123683,"e_wo_entrp":-11.48059295,"e_0_energy":-11.48091489,"forces":[[-0.0,-0.0,-0.0],[0.0,0.0,0.0]],"stress":[[-11.94991105,-0.0,0.0],[-0.0,-11.94991105,-0.0],[0.0,0.0,-11.94991105]],"electronic_steps":[{"alphaZ":3.30899841,"ewald":-227.30768138,"hartreedc":-11.25054504,"XCdc":-17.44029463,"pawpsdc":174.89845602,"pawaedc":-140.31916047,"eentropy":-0.00576862,"bandstr":7.4477054,"atom":205.15160006,"e_fr_energy":-5.51669025,"e_wo_entrp":-5.51092163,"e_0_energy":-5.51380594},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.5030273,"e_wo_entrp":-11.50196668,"e_0_energy":-11.50249699},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.50956333,"e_wo_entrp":-11.50850279,"e_0_energy":-11.50903306},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.50956706,"e_wo_entrp":-11.50850652,"e_0_energy":-11.50903679},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.50956706,"e_wo_entrp":-11.50850652,"e_0_energy":-11.50903679},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.53611896,"e_wo_entrp":-11.53582946,"e_0_energy":-11.53597421},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.45975595,"e_wo_entrp":-11.45885776,"e_0_energy":-11.45930686},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48088697,"e_wo_entrp":-11.48018417,"e_0_energy":-11.48053557},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48108984,"e_wo_entrp":-11.48040567,"e_0_energy":-11.48074775},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48120487,"e_wo_entrp":-11.48055795,"e_0_energy":-11.48088141},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48124463,"e_wo_entrp":-11.48060003,"e_0_energy":-11.48092233},{"alphaZ":3.30899841,"ewald":-227.30768138,"hartreedc":-14.82023784,"XCdc":-16.9157322,"pawpsdc":843.38594458,"pawaedc":-809.01255792,"eentropy":-0.00064389,"bandstr":4.72907334,"atom":205.15160006,"e_fr_energy":-11.48123683,"e_wo_entrp":-11.48059295,"e_0_energy":-11.48091489}],"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[0.0,2.73,2.73],[2.73,0.0,2.73],[2.73,2.73,0.0]],"pbc":[true,true,true],"a":3.8608030252785492,"b":3.8608030252785492,"c":3.8608030252785492,"alpha":59.99999999999999,"beta":59.99999999999999,"gamma":59.99999999999999,"volume":40.692834},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.0,0.0],"xyz":[0.0,0.0,0.0],"properties":{},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.365,1.365,1.365],"properties":{},"label":"Si"}]}},{"e_fr_energy":-11.48232167,"e_wo_entrp":-11.48151129,"e_0_energy":-11.48191648,"forces":[[-0.0,0.0,-0.0],[0.0,-0.0,0.0]],"stress":[[8.312558,0.0,0.0],[0.0,8.312558,0.0],[0.0,-0.0,8.312558]],"electronic_steps":[{"alphaZ":3.38275168,"ewald":-228.98408474,"hartreedc":-14.93040698,"XCdc":-16.81647568,"pawpsdc":840.23106792,"pawaedc":-805.85763374,"eentropy":-0.00099223,"bandstr":6.33884318,"atom":205.15160006,"e_fr_energy":-11.48533053,"e_wo_entrp":-11.4843383,"e_0_energy":-11.48483442},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48327646,"e_wo_entrp":-11.48237268,"e_0_energy":-11.48282457},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48232378,"e_wo_entrp":-11.48151821,"e_0_energy":-11.481921},{"alphaZ":3.38275168,"ewald":-228.98408474,"hartreedc":-14.56699686,"XCdc":-16.8223405,"pawpsdc":886.45497495,"pawaedc":-852.09684853,"eentropy":-0.00081037,"bandstr":5.99943265,"atom":205.15160006,"e_fr_energy":-11.48232167,"e_wo_entrp":-11.48151129,"e_0_energy":-11.48191648}],"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[-0.0,2.71001354,2.71001354],[2.71001354,0.0,2.71001354],[2.71001354,2.71001354,0.0]],"pbc":[true,true,true],"a":3.8325379024827217,"b":3.8325379024827217,"c":3.8325379024827217,"alpha":59.99999999999999,"beta":59.99999999999999,"gamma":59.99999999999999,"volume":39.80561863766497},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[-0.0,-0.0,-0.0],"xyz":[0.0,0.0,0.0],"properties":{},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.35500677,1.35500677,1.35500677],"properties":{},"label":"Si"}]}},{"e_fr_energy":-11.48325744,"e_wo_entrp":-11.48251822,"e_0_energy":-11.48288783,"forces":[[0.0,0.0,0.0],[-0.0,-0.0,-0.0]],"stress":[[0.04088458,0.0,-0.0],[0.0,0.04088458,0.0],[0.0,-0.0,0.04088458]],"electronic_steps":[{"alphaZ":3.35262593,"ewald":-228.30230284,"hartreedc":-14.52175313,"XCdc":-16.86205909,"pawpsdc":881.66215819,"pawaedc":-847.30559099,"eentropy":-0.00067543,"bandstr":5.34224671,"atom":205.15160006,"e_fr_energy":-11.4837506,"e_wo_entrp":-11.48307517,"e_0_energy":-11.48341288},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48341833,"e_wo_entrp":-11.48271382,"e_0_energy":-11.48306607},{"alphaZ":null,"ewald":null,"hartreedc":null,"XCdc":null,"pawpsdc":null,"pawaedc":null,"eentropy":null,"bandstr":null,"atom":null,"e_fr_energy":-11.48325844,"e_wo_entrp":-11.4825187,"e_0_energy":-11.48288857},{"alphaZ":3.35262593,"ewald":-228.30230284,"hartreedc":-14.66693957,"XCdc":-16.85933152,"pawpsdc":859.83950703,"pawaedc":-825.47718253,"eentropy":-0.00073922,"bandstr":5.47950522,"atom":205.15160006,"e_fr_energy":-11.48325744,"e_wo_entrp":-11.48251822,"e_0_energy":-11.48288783}],"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[-0.0,2.71810649,2.71810649],[2.71810649,0.0,2.71810649],[2.71810649,2.71810649,0.0]],"pbc":[true,true,true],"a":3.843983062132329,"b":3.843983062132329,"c":3.843983062132329,"alpha":59.99999999999999,"beta":59.99999999999999,"gamma":59.99999999999999,"volume":40.163300833521646},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[-0.0,-0.0,-0.0],"xyz":[0.0,0.0,0.0],"properties":{},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.359053245,1.359053245,1.359053245],"properties":{},"label":"Si"}]}}],"locpot":null,"outcar":{"@module":"pymatgen.io.vasp.outputs","@class":"Outcar","efermi":5.9685,"magnetization":[{"s":-0.0,"p":0.0,"d":0.0,"tot":-0.0},{"s":-0.0,"p":0.0,"d":0.0,"tot":-0.0}],"charge":[{"s":0.751,"p":0.938,"d":0.0,"tot":1.689},{"s":0.751,"p":0.938,"d":0.0,"tot":1.689}],"total_magnetization":-5.1e-6,"nelect":8.0,"is_stopped":false,"drift":[[0.0,0.0,-0.0],[0.0,0.0,-0.0],[0.0,0.0,-0.0]],"ngf":[72,72,72],"sampling_radii":[0.9892],"electrostatic_potential":[-83.0676,-83.0676]},"force_constants":null,"normalmode_frequencies":null,"normalmode_eigenvals":null,"normalmode_eigenvecs":null,"elph_displaced_structures":{"temperatures":null,"structures":null},"dos_properties":{"Si":{"s":{"filling":0.4427601717036412,"center":6.0420383388504755,"bandwidth":15.846281139043978,"skewness":0.7981832261655295,"kurtosis":2.486314542519376,"upper_edge":-6.39203235},"p":{"filling":0.2091359960478043,"center":14.073327227948507,"bandwidth":13.877364959477802,"skewness":0.4111522709467528,"kurtosis":2.1841902117142857,"upper_edge":6.713967649999999}}},"run_stats":{"average_memory":0.0,"max_memory":241584.0,"elapsed_time":18.833,"system_time":1.114,"user_time":16.166,"total_time":17.28,"cores":40}},"completed_at":"2024-05-19 17:13:34.897366","task_name":"standard","output_file_paths":{"chgcar":"CHGCAR","aeccar0":"AECCAR0","aeccar1":"AECCAR1","aeccar2":"AECCAR2"},"bader":null,"ddec6":null,"run_type":"PBESol","task_type":"Structure Optimization","calc_type":"PBESol Structure Optimization"}],"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[-0.0,2.7181064862403606,2.7181064862403606],[2.7181064862403606,0.0,2.7181064862403606],[2.7181064862403606,2.7181064862403606,0.0]],"pbc":[true,true,true],"a":3.8439830568153965,"b":3.8439830568153965,"c":3.8439830568153965,"alpha":60.00000000000001,"beta":60.00000000000001,"gamma":60.00000000000001,"volume":40.163300666862035},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[-0.0,-0.0,-0.0],"xyz":[0.0,0.0,0.0],"properties":{"magmom":-0.0},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.3590532431201803,1.3590532431201803,1.3590532431201803],"properties":{"magmom":-0.0},"label":"Si"}]},"task_type":"Structure Optimization","task_id":null,"orig_inputs":{"incar":{"ALGO":"Fast","EDIFF":0.00001,"EDIFFG":-0.02,"ENAUG":1360,"ENCUT":680,"GGA":"Ps","IBRION":2,"ISIF":3,"ISMEAR":0,"ISPIN":2,"LAECHG":true,"LASPH":true,"LCHARG":false,"LELF":false,"LMIXTAU":true,"LORBIT":11,"LREAL":false,"LVTOT":false,"LWAVE":false,"MAGMOM":[0.6,0.6],"NELM":200,"NSW":99,"PREC":"Accurate","SIGMA":0.2},"poscar":{"@module":"pymatgen.io.vasp.inputs","@class":"Poscar","structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0,"lattice":{"matrix":[[0.0,2.73,2.73],[2.73,0.0,2.73],[2.73,2.73,0.0]],"pbc":[true,true,true],"a":3.8608030252785492,"b":3.8608030252785492,"c":3.8608030252785492,"alpha":59.99999999999999,"beta":59.99999999999999,"gamma":59.99999999999999,"volume":40.692834},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.0,0.0],"xyz":[0.0,0.0,0.0],"properties":{},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.365,1.365,1.365],"properties":{},"label":"Si"}]},"true_names":true,"selective_dynamics":null,"velocities":null,"predictor_corrector":null,"comment":"Si2"},"kpoints":{"comment":"Automatic kpoint scheme","nkpoints":0,"generation_style":"Gamma","kpoints":[[7,7,7]],"usershift":[0,0,0],"kpts_weights":null,"coord_type":null,"labels":null,"tet_number":0,"tet_weight":0,"tet_connections":null,"@module":"pymatgen.io.vasp.inputs","@class":"Kpoints"},"potcar":[{"titel":"Si","hash":"c27340a9c98542122fbad458bbb5d441","summary_stats":{"keywords":{"header":["dexc","eatom","eaug","enmax","enmin","icore","iunscr","lcor","lexch","lpaw","lultra","ndata","orbitaldescriptions","orbitals","pomass","raug","rcore","rdep","rdept","rmax","rpacor","rrkj","rwigs","step","titel","vrhfin","zval","nentries"],"data":["localpart","gradientcorrectionsusedforxc","corecharge-density(partial)","kineticenergydensity(partial)","atomicpseudocharge-density","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","pawradialsets","(5e20.12)","augmentationcharges(nonsperical)","uccopanciesinatom","grid","aepotential","corecharge-density","kineticenergy-density","mkineticenergy-densitypseudized","localpseudopotentialcore","pspotentialvalenceonly","corecharge-density(pseudized)","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","endofdataset"]},"stats":{"header":{"MEAN":9.198469218699186,"ABSMEAN":9.198469218699186,"VAR":1790.7147656424072,"MIN":0.0,"MAX":322.069},"data":{"MEAN":215.16613596661992,"ABSMEAN":237.9507629282115,"VAR":3381771.445249609,"MIN":-872.57185,"MAX":24929.6947974}}}}]},"input":{"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[0.0,2.73,2.73],[2.73,0.0,2.73],[2.73,2.73,0.0]],"pbc":[true,true,true],"a":3.8608030252785492,"b":3.8608030252785492,"c":3.8608030252785492,"alpha":59.99999999999999,"beta":59.99999999999999,"gamma":59.99999999999999,"volume":40.692834},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[0.0,0.0,0.0],"xyz":[0.0,0.0,0.0],"properties":{},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.365,1.365,1.365],"properties":{},"label":"Si"}]},"parameters":{"SYSTEM":"unknown system","LCOMPAT":false,"PREC":"accura","ENMAX":680.0,"ENAUG":1360.0,"EDIFF":0.00001,"IALGO":68,"IWAVPR":11,"NBANDS":40,"NBANDSLOW":-1,"NBANDSHIGH":-1,"NELECT":8.0,"TURBO":0,"IRESTART":0,"NREBOOT":0,"NMIN":0,"EREF":0.0,"ISMEAR":0,"SIGMA":0.2,"KSPACING":0.5,"KGAMMA":true,"KBLOWUP":true,"LREAL":false,"ROPT":[0.0],"LMAXPAW":-100,"LMAXMIX":2,"NLSPLINE":false,"ISTART":0,"ICHARG":2,"INIWAV":1,"ISPIN":2,"LNONCOLLINEAR":false,"MAGMOM":[0.6,0.6],"NUPDOWN":-1.0,"LSORBIT":false,"SAXIS":[0.0,0.0,1.0],"LSPIRAL":false,"QSPIRAL":[0.0,0.0,0.0],"LZEROZ":false,"LASPH":true,"LMETAGGA":false,"NELM":200,"NELMDL":-5,"NELMIN":2,"ENINI":680.0,"LDIAG":true,"LSUBROT":false,"WEIMIN":0.001,"EBREAK":6e-8,"DEPER":0.3,"NRMM":4,"TIME":0.4,"AMIX":0.4,"BMIX":1.0,"AMIN":0.1,"AMIX_MAG":1.6,"BMIX_MAG":1.0,"IMIX":4,"MIXFIRST":false,"MAXMIX":-45,"WC":100.0,"INIMIX":1,"MIXPRE":1,"MREMOVE":5,"LDIPOL":false,"LMONO":false,"IDIPOL":0,"EPSILON":1.0,"DIPOL":[-100.0,-100.0,-100.0],"EFIELD":0.0,"NGX":36,"NGY":36,"NGZ":36,"NGXF":72,"NGYF":72,"NGZF":72,"ADDGRID":false,"NSW":99,"IBRION":2,"MDALGO":0,"ISIF":3,"PSTRESS":0.0,"EDIFFG":-0.02,"NFREE":1,"POTIM":0.5,"SMASS":-3.0,"SCALEE":1.0,"TEBEG":0.0001,"TEEND":0.0001,"NBLOCK":1,"KBLOCK":99,"NPACO":256,"APACO":10.0,"ISYM":2,"SYMPREC":0.00001,"LORBIT":11,"RWIGS":[-1.0],"NEDOS":301,"EMIN":10.0,"EMAX":-10.0,"EFERMI":0.0,"NWRITE":2,"LWAVE":false,"LDOWNSAMPLE":false,"LCHARG":false,"LPARD":false,"LVTOT":false,"LVHAR":false,"LELF":false,"LOPTICS":false,"STM":[0.0,0.0,0.0,0.0,0.0,0.0,0.0],"NPAR":40,"NSIM":4,"NBLK":-1,"LPLANE":true,"LSCALAPACK":true,"LSCAAWARE":false,"LSCALU":false,"LASYNC":false,"LORBITALREAL":false,"IDIOT":3,"PHON_NSTRUCT":-1,"LMUSIC":false,"POMASS":[28.085],"DARWINR":[0.0],"DARWINV":[1.0],"LCORR":true,"GGA_COMPAT":true,"LBERRY":false,"ICORELEVEL":0,"LDAU":false,"I_CONSTRAINED_M":0,"GGA":"PS","VOSKOWN":0,"LHFCALC":false,"PRECFOCK":"","LSYMGRAD":false,"LHFONE":false,"LRHFCALC":false,"LTHOMAS":false,"LMODELHF":false,"LFOCKACE":false,"ENCUT4O":-1.0,"EXXOEP":0,"FOURORBIT":0,"AEXX":0.0,"HFALPHA":0.0,"MCALPHA":0.0,"ALDAX":1.0,"AGGAX":1.0,"ALDAC":1.0,"AGGAC":1.0,"NKREDX":1,"NKREDY":1,"NKREDZ":1,"SHIFTRED":false,"ODDONLY":false,"EVENONLY":false,"LMAXFOCK":0,"NMAXFOCKAE":0,"LFOCKAEDFT":false,"HFSCREEN":0.0,"HFSCREENC":0.0,"NBANDSGWLOW":0,"LUSE_VDW":false,"IVDW_NL":1,"LSPIN_VDW":false,"Zab_VDW":-0.8491,"PARAM1":0.1234,"PARAM2":1.0,"PARAM3":0.0,"MODEL_GW":0,"MODEL_EPS0":12.2078502,"MODEL_ALPHA":1.0,"LEPSILON":false,"LRPA":false,"LNABLA":false,"LVEL":false,"CSHIFT":0.1,"OMEGAMAX":-1.0,"DEG_THRESHOLD":0.002,"RTIME":-0.1,"WPLASMAI":0.0,"DFIELD":[0.0,0.0,0.0],"WPLASMA":[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0],"NUCIND":false,"MAGPOS":[0.0,0.0,0.0],"LNICSALL":true,"ORBITALMAG":false,"LMAGBLOCH":false,"LCHIMAG":false,"LGAUGE":true,"MAGATOM":0,"MAGDIPOL":[0.0,0.0,0.0],"AVECCONST":[0.0,0.0,0.0],"LALL_IN_ONE":false,"IALL_IN_ONE":-1,"NBANDS_WAVE":-1,"LFINITE_TEMPERATURE":false,"LADDER":false,"LRPAFORCE":false,"LFXC":false,"LHARTREE":true,"IBSE":0,"KPOINT":[-1,0,0,0],"LTCTC":false,"LTCTE":false,"LTETE":false,"LTRIPLET":false,"LFXCEPS":false,"LFXHEG":false,"NATURALO":2,"LHOLEGF":false,"L2ORDER":false,"LDMP1":false,"LMP2LT":false,"LSMP2LT":false,"LGWLF":false,"ENCUTGW":-1.60000002,"ENCUTGWSOFT":-1.60000002,"ENCUTLF":-1.0,"LESF_SPLINES":false,"LMAXMP2":-1,"SCISSOR":0.0,"NOMEGA":0,"NOMEGAR":0,"NBANDSGW":-1,"NBANDSO":-1,"NBANDSV":-1,"NELMGW":1,"NELMHF":1,"DIM":3,"IESPILON":4,"ANTIRES":0,"OMEGAMIN":-30.0,"OMEGATL":-200.0,"OMEGAGRID":0,"LSELFENERGY":false,"LSPECTRAL":false,"LSPECTRALGW":false,"LSINGLES":false,"LFERMIGW":false,"ODDONLYGW":false,"EVENONLYGW":false,"NKREDLFX":1,"NKREDLFY":1,"NKREDLFZ":1,"MAXMEM":2800,"TELESCOPE":0,"NTAUPAR":-1,"NOMEGAPAR":-1,"DAMP_NEWTON":0.80000001,"LAMBDA":1.0,"OFIELD_KAPPA":0.0,"OFIELD_K":[0.0,0.0,0.0],"OFIELD_Q6_NEAR":0.0,"OFIELD_Q6_FAR":0.0,"OFIELD_A":0.0,"KPOINTS_OPT_MODE":1,"LKPOINTS_OPT":false},"pseudo_potentials":{"pot_type":"PAW","functional":"P_B_E","symbols":["PAW_PBE"]},"potcar_spec":[{"titel":"PAW_PBE Si 05Jan2001","hash":"c27340a9c98542122fbad458bbb5d441","summary_stats":{"keywords":{"header":["dexc","eatom","eaug","enmax","enmin","icore","iunscr","lcor","lexch","lpaw","lultra","ndata","orbitaldescriptions","orbitals","pomass","raug","rcore","rdep","rdept","rmax","rpacor","rrkj","rwigs","step","titel","vrhfin","zval","nentries"],"data":["localpart","gradientcorrectionsusedforxc","corecharge-density(partial)","kineticenergydensity(partial)","atomicpseudocharge-density","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","pawradialsets","(5e20.12)","augmentationcharges(nonsperical)","uccopanciesinatom","grid","aepotential","corecharge-density","kineticenergy-density","mkineticenergy-densitypseudized","localpseudopotentialcore","pspotentialvalenceonly","corecharge-density(pseudized)","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","endofdataset"]},"stats":{"header":{"MEAN":9.198469218699186,"ABSMEAN":9.198469218699186,"VAR":1790.7147656424072,"MIN":0.0,"MAX":322.069},"data":{"MEAN":215.16613596661992,"ABSMEAN":237.9507629282115,"VAR":3381771.445249609,"MIN":-872.57185,"MAX":24929.6947974}}}}],"xc_override":"PS","is_lasph":true,"is_hubbard":false,"hubbards":{},"magnetic_moments":[0.6,0.6]},"output":{"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[-0.0,2.7181064862403606,2.7181064862403606],[2.7181064862403606,0.0,2.7181064862403606],[2.7181064862403606,2.7181064862403606,0.0]],"pbc":[true,true,true],"a":3.8439830568153965,"b":3.8439830568153965,"c":3.8439830568153965,"alpha":60.00000000000001,"beta":60.00000000000001,"gamma":60.00000000000001,"volume":40.163300666862035},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[-0.0,-0.0,-0.0],"xyz":[0.0,0.0,0.0],"properties":{"magmom":-0.0},"label":"Si"},{"species":[{"element":"Si","occu":1}],"abc":[0.25,0.25,0.25],"xyz":[1.3590532431201803,1.3590532431201803,1.3590532431201803],"properties":{"magmom":-0.0},"label":"Si"}]},"density":2.3223723738160613,"energy":-11.48288783,"forces":[[0.0,0.0,0.0],[-0.0,-0.0,-0.0]],"stress":[[0.04088458,0.0,-0.0],[0.0,0.04088458,0.0],[0.0,-0.0,0.04088458]],"energy_per_atom":-5.741443915,"bandgap":0.45999999999999996},"included_objects":null,"vasp_objects":{},"entry":{"@module":"pymatgen.entries.computed_entries","@class":"ComputedEntry","energy":-11.48288783,"composition":{"Si":2.0},"entry_id":null,"correction":0.0,"energy_adjustments":[],"parameters":{"potcar_spec":[{"titel":"PAW_PBE Si 05Jan2001","hash":"c27340a9c98542122fbad458bbb5d441","summary_stats":{"keywords":{"header":["dexc","eatom","eaug","enmax","enmin","icore","iunscr","lcor","lexch","lpaw","lultra","ndata","orbitaldescriptions","orbitals","pomass","raug","rcore","rdep","rdept","rmax","rpacor","rrkj","rwigs","step","titel","vrhfin","zval","nentries"],"data":["localpart","gradientcorrectionsusedforxc","corecharge-density(partial)","kineticenergydensity(partial)","atomicpseudocharge-density","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","nonlocalpart","reciprocalspacepart","realspacepart","reciprocalspacepart","realspacepart","pawradialsets","(5e20.12)","augmentationcharges(nonsperical)","uccopanciesinatom","grid","aepotential","corecharge-density","kineticenergy-density","mkineticenergy-densitypseudized","localpseudopotentialcore","pspotentialvalenceonly","corecharge-density(pseudized)","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","pseudowavefunction","aewavefunction","endofdataset"]},"stats":{"header":{"MEAN":9.198469218699186,"ABSMEAN":9.198469218699186,"VAR":1790.7147656424072,"MIN":0.0,"MAX":322.069},"data":{"MEAN":215.16613596661992,"ABSMEAN":237.9507629282115,"VAR":3381771.445249609,"MIN":-872.57185,"MAX":24929.6947974}}}}],"run_type":"PBESol","is_hubbard":false,"hubbards":{}},"data":{"oxide_type":"None","aspherical":true,"last_updated":"2024-05-19 21:13:45.541962"}},"task_label":"relax","author":null,"icsd_id":null,"transformations":{},"additional_json":{},"custodian":[{"corrections":[],"job":{"@module":"custodian.vasp.jobs","@class":"VaspJob","@version":"2024.4.18","vasp_cmd":["srun","/scratch/gpfs/ab6989/MPScanRelaxSet/atomate2/vasp_std"],"output_file":"vasp.out","stderr_file":"std_err.txt","suffix":"","final":true,"backup":true,"auto_npar":false,"auto_gamma":true,"settings_override":null,"gamma_vasp_cmd":["vasp_gam"],"copy_magmom":false,"auto_continue":false}}],"analysis":{"delta_volume":-0.5295333331379624,"delta_volume_percent":-1.3012938178205096,"max_force":0.0,"warnings":[],"errors":[]},"last_updated":null,"include_structure":true,"completed_at":"2024-05-19 17:13:34.897366","run_stats":{"standard":{"average_memory":0.0,"max_memory":241584.0,"elapsed_time":18.833,"system_time":1.114,"user_time":16.166,"total_time":17.28,"cores":40},"overall":{"average_memory":0.0,"max_memory":241584.0,"elapsed_time":18.833,"system_time":1.114,"user_time":16.166,"total_time":17.28,"cores":40}},"@module":"emmet.core.tasks","@class":"TaskDoc","@version":null},"completed_at":"2024-05-19T17:13:46.400349","metadata":{},"hosts":["dbaebabf-134d-426a-b91c-15abf799da65"],"name":"relax","@module":"jobflow.core.schemas","@class":"JobStoreDocument","@version":"0.1.17"}] diff --git a/docs/index.md b/docs/index.md index 32f20ccbb8..a8a0382698 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,7 @@ user/index user/install user/running-workflows +user/docs-schemas-emmet user/fireworks user/atomate-1-vs-2 user/codes/index diff --git a/docs/user/docs_schemas_emmet.md b/docs/user/docs_schemas_emmet.md new file mode 100644 index 0000000000..70004263b7 --- /dev/null +++ b/docs/user/docs_schemas_emmet.md @@ -0,0 +1,506 @@ +(docs_schemas_emmet)= + +# An introduction to task documents, schemas, and emmet + +## Introduction + +If you have been [running-workflows](running_workflows), you are now starting +to generate data. `atomate2` stores both input and output data for every step of +its workflows in Task Documents. Task Documents define a *schema* or structure for +organizing information from different types of calculations, which then facilitates +automatic processing with tools like `emmet` or `maggma`. This tutorial will familiarize you with +these basic concepts. + +### Objectives + +* Understand how `atomate2` stores and organizes calculation data +* Explain the meaning of a "Document Model" or schema +* Inspect a `TaskDoc` generated by `atomate2` + +### Prerequisites + +To complete this tutorial, you need + +* A working installation of `atomate2` +* (optional) to complete the [running workflows](running-workflows.md) tutorial. + +## How `atomate2` stores and organizes data. + +As explained in [Configure calculation output database](install.md#configure-calculation-output-database), `atomate2` +stores the results of every `Job` in a database. More specifically, `atomate2` uses a +[`maggma.Store`](https://materialsproject.github.io/maggma/getting_started/stores/) to interface with a data storage backend +(usually MongoDB). Data is stored in a `JSON`-like or python `dict`-like format, which you can think of as a list of +dictionaries, where each dictionary represents one `Job`. Each dictionary in the list is called a "document", +so "document" refers to the output data from a single `Job `. + +To facilitate automated processing and analysis, it's important that every document follows a +consistent format. That's where schemas (also called "Document Models") come in. + +## Document Models + +### Schema for `Job` + +Document models define a specific format (i.e., structure and data types) for a given `Job` or calculation. +`atomate2` uses [pydantic](https://docs.pydantic.dev/latest/) to define these schemas. If you'd like +to learn more about `pydantic`, we suggest reading [this introduction]( +https://realpython.com/python-pydantic/#getting-familiar-with-pydantic). In brief, every Document Model in `atomate2` +is an instance of `pydantic.BaseModel`. The `BaseModel` is then turned into a `dict` (serialized) before being +inserted into the store. + +To understand how this works, we are going to look at the output data from a structural relaxation for Si. If we +examine the `docs` store after running this `Job`, we will see something similar to the following: + +```json +[ + {"uuid":"c2b5eb7d-838b-4dee-896f-95f21867b62b", + "index":1, + "output":{...}, + "completed_at":"2024-05-19T17:13:46.400349", + "metadata":{}, + "hosts":["dbaebabf-134d-426a-b91c-15abf799da65"], + "name":"relax", + "@module":"jobflow.core.schemas", + "@class":"JobStoreDocument", + "@version":"0.1.17" + }, +] +``` + + +This document follows a schema (`JobStoreDocument`, defined [here](https://github.com/materialsproject/jobflow/blob/main/src/jobflow/core/schemas.py)) +that contains information about the `Job`, such as: + - `uuid`: a unique identifier for the `Job` + - `output`: The actual job output (e.g., calculation results). We'll examine this in the next section. + - `completed_at`: The time the job was completed. + - `name`: The name of the job (in this case "relax" because we did a structure relaxation) + - `@module`, `@class`, `@version`: These keys store the specific origin and version of the document model so that it can + be easily re-created from the `dict`. + +Because every `atomate2` document is first created as a `JobStoreDocument` before being inserted into the database, +you can be assured that every `Job` you run will contain these keys. Document Models have the additional benefit +of validating the data types, so for example, `name` is guaranteed to a `str`, whereas `index` is guaranteed to be a `int`. + +```{warning} +In this tutorial, we show only **excerpts** of the output data to highlight key points. For example, +in the box above we have collapsed the `outputs` key. You are encouraged to open the +[complete output data (`.json` format)](../_static/docs_store_Si_relax.json) in a separate tab of your web browser +and refer to it as you read through this tutorial. +``` + +### Schema for `output` + +The output data for the calculation itself (the contents of the `Job`) are stored in the `output` key. **The schema +of `output` will vary depending on the type of calculation (e.g., VASP relaxation, Q-Chem static, etc.), but will +always be consistent for a particular `Job` type**. In the case of a VASP calculation, the schema is called +a `TaskDoc`. + +That being said, most `Job` types have a few features in common, which we will highlight in our example. If we look +at the top-level keys of `output` from the `JobStoreDocument` in the previous section, we see: + +```json +{ + "builder_meta": {...} + "nsites": 2, + "elements": ["Si"], + "nelements": 1, + "composition": {"Si": 2}, + "composition_reduced": {"Si": 1}, + "formula_pretty": "Si", + "formula_anonymous": "A", + "chemsys": "Si", + "volume": 40.163300666862035, + "density": 2.3223723738160613, + "density_atomic": 20.081650333431018, + "symmetry": {...}, + "tags": null, + "dir_name": "/scratch/gpfs/.../job_2024-05-19-21-13-15-058677-64911", + "state": "successful", + "calcs_reversed": [...], + "structure": {...}, + "task_type": "Structure Optimization", + "task_id": null, + "orig_inputs": {...}, + "input": {...}, + "output": {...}, + "@module": "emmet.core.tasks", + "@class": "TaskDoc", + "@version": null +} +``` + +Even though we are looking at an example for a VASP calculations, **`atomate2` uses hierarchical or modular Document +Models wherever possible**. Therefore, the Task Documents generated for other calculation types have the same +general structure (e.g., `inputs`, `outputs`, structure metadata, `custodian`, `orig_inputs`, `calcs_reversed`, etc.) + +We describe many of these top-level keys in more detail in the following subsections. + +```{note} +You can also generate `TaskDoc` from VASP calculations that you have run manually. To do + so, use the `from_directory` class method: + ```python + from emmet.core.tasks import TaskDoc + doc = TaskDoc.from_directory("") +``` + +#### Structure Metadata + +The root level of the `TaskDoc` has keys containing basic structural information including: + - `nsites`: The number of sites + - `composition`: Full composition for the material. + - `elements`: List of elements in the material. + - `formula_pretty`: Cleaned representation of the formula. + - `chemsys`: dash-delimited string of elements in the material. + +And more. These keys illustrate another principle of Document Models -- they are +**hierarchical**. Specifically, the structure metadata keys are populated by _another_ `pydantic` schema called +[StructureMetadata](https://github.com/materialsproject/emmet/blob/efc0b22ff835b11b1c825cbc93d4bbebf84a0d91/emmet-core/emmet/core/structure.py#L18) +defined in `emmet`. So the `TaskDoc` schema comprises several subsidiary models that organize different types of +information, as discussed further below. + +#### `structure` + +The `structure` key contains the **final output structure** of the calculation as a serialized `pymatgen.Structure` object. + +```json +"structure": { + "@module": "pymatgen.core.structure", + "@class": "Structure", + "charge": 0, + "lattice": {...}, + "properties": {}, + "sites": [...] + } +``` + +#### `builder_meta` + +The `builder_meta` key contains information about the software used to generate the data in the `TaskDoc`. Here is the +example from our structure relaxation: + +```json +"builder_meta": { + "emmet_version": "0.83.0", + "pymatgen_version": "2024.4.13", + "pull_request": null, + "database_version": null, + "build_date": "2024-05-19T21:13:45.541000", + "license": null + } +``` + +#### Calculation metadata: `dir_name`, `run_stats`, `task_label`, and `task_type` + +- `task_label`: A user-definable label for the specific calculation +- `task_type`: A standardized label specifying the specific type of calculation being performed. +- `dir_name`: The path of the directory in which input/output files were written +- `run_stats`: Information about the walltime, cpu time, and computational resources utilized. + +```json +"task_type": "Structure Optimization", +"task_label": "relax", +"dir_name": "della-r3c1n3:/scratch/gpfs/ab6989/MPScanRelaxSet/atomate2/Ca_Mg_runs/job_2024-05-19-21-13-15-058677-64911", +"run_stats": { + "average_memory": 0, + "max_memory": 241584, + "elapsed_time": 18.833, + "system_time": 1.114, + "user_time": 16.166, + "total_time": 17.28, + "cores": 40 + } +``` + +#### Calculation Inputs + +`atomate2` stores a record of not just the outputs of a calculation, but also the inputs, and any modifications that +were made to those inputs. + +The `input` key contains the **summarized final input data for the calculation**. It's schema is defined by +[InputDoc](https://github.com/materialsproject/emmet/blob/efc0b22ff835b11b1c825cbc93d4bbebf84a0d91/emmet-core/emmet/core/tasks.py#L175) +and includes everything one needs to specify a VASP calculation: a `Structure` object, INCAR settings, +Pseudopotential specifications, etc. Let's just look at the top-level keys of our `input` section: + +```json +"input": { + "structure": {...}, + "parameters": {...}, + "pseudo_potentials": {...}, + "potcar_spec": [ ... ], + "xc_override": "PS", + "is_lasph": true, + "is_hubbard": false, + "hubbards": {}, + "magnetic_moments": [ + 0.6, + 0.6 + ] + }, +``` + +#### Calculation Outputs + +Much like `input`, the `output` key is populated by a nested schema called [`OutputDoc`](https://github.com/materialsproject/emmet/blob/efc0b22ff835b11b1c825cbc93d4bbebf84a0d91/emmet-core/emmet/core/tasks.py#L97). +`OutputDoc` captures key summary information about the final result of a VASP calculation, including the `Structure`, final energy, `energy_per_atom`, and `bandgap`. In our example: + +```json +"output": { + "structure": {...}, + "density": 2.3223723738160613, + "energy": -11.48288783, + "forces": [ + [ + 0, + 0, + 0 + ], + [ + 0, + 0, + 0 + ] + ], + "stress": [ + [ + 0.04088458, + 0, + 0 + ], + [ + 0, + 0.04088458, + 0 + ], + [ + 0, + 0, + 0.04088458 + ] + ], + "energy_per_atom": -5.741443915, + "bandgap": 0.45999999999999996 + }, + +``` + + + + +#### `custodian` and `orig_inputs` + +There is also a key called `orig_inputs` that contains the **original inputs given by the user** when the calculation +was launched. It is possible for `input` and `orig_inputs` to differ if `custodian` is invoked to apply some adjustment +to the calculation settings. `orig_inputs` is retained to provide 100% transparent provenance in such cases. + +In addition, there is a `custodian` key that will capture and list any corrections or changes made by `custodian` +during the calculation, as well as additional metadata. In our case, the `custodian.corrections` list is empty, +which means that no modifications or restarts were made. + +```json +"custodian": [ + { + "corrections": [], + "job": { + "@module": "custodian.vasp.jobs", + "@class": "VaspJob", + "@version": "2024.4.18", + "vasp_cmd": [ + "srun", + "/scratch/gpfs/ab6989/MPScanRelaxSet/atomate2/vasp_std" + ], + "output_file": "vasp.out", + "stderr_file": "std_err.txt", + "suffix": "", + "final": true, + "backup": true, + "auto_npar": false, + "auto_gamma": true, + "settings_override": null, + "gamma_vasp_cmd": [ + "vasp_gam" + ], + "copy_magmom": false, + "auto_continue": false + } + } + ], +``` + +#### `calcs_reversed` + +Most Task Documents also contain a key called `calcs_reversed` which, as the name implies, contains calculation inputs +and outputs **in reverse order**. These are stored as a `list`, so index `[0]` corresponds to the last (most recent) +calculation, whereas index `[-1]` is the first calculation. Each element in the list contains `input`, `output`, `dir_name`, +and other keys that give a complete specification of that calculation step. + +In this example, there is only one element in `calcs_reversed`, because we just did a one-step `Job`. However, more +complex workflows that contain multiple individual calculations would have an entry for each step. + +```json +"calcs_reversed": [ + { "dir_name": "/scratch/gpfs/.../job_2024-05-19-21-13-15-058677-64911", + "vasp_version": "6.4.2", + "has_vasp_completed": "successful", + "input": { + "incar": {...}, + "kpoints": {...}, + "nkpoints": 20, + "potcar": ["PAW_PBE"], + "potcar_spec": [ ... ], + "potcar_type": ["PAW_PBE"], + "parameters": {...}, + "lattice_rec": {...}, + "structure": {...}, + "is_hubbard": false, + "hubbards": {} + }, + "output": { + "energy": -11.48288783, + "energy_per_atom": -5.741443915, + "structure": { .... }, + "efermi": 5.96853235, + "is_metal": false, + "bandgap": 0.45999999999999996, + "cbm": 6.2225, + "vbm": 5.7625, + "is_gap_direct": false, + "direct_gap": 2.5146000000000006, + "transition": "(0.000,0.000,0.000)-(0.429,0.429,-0.000)", + "mag_density": -1.2698159551931228e-7, + "epsilon_static": null, + "epsilon_static_wolfe": null, + "epsilon_ionic": null, + "frequency_dependent_dielectric": { + "real": null, + "imaginary": null, + "energy": null + }, + "ionic_steps": [ ... ], + "force_constants": null, + "normalmode_frequencies": null, + "normalmode_eigenvals": null, + "normalmode_eigenvecs": null, + "elph_displaced_structures": { + "temperatures": null, + "structures": null + }, + "dos_properties": {...}, + "run_stats": { + "average_memory": 0, + "max_memory": 241584, + "elapsed_time": 18.833, + "system_time": 1.114, + "user_time": 16.166, + "total_time": 17.28, + "cores": 40 + } + }, + "completed_at": "2024-05-19 17:13:34.897366", + "task_name": "standard", + "output_file_paths": { + "chgcar": "CHGCAR", + "aeccar0": "AECCAR0", + "aeccar1": "AECCAR1", + "aeccar2": "AECCAR2" + }, + "bader": null, + "ddec6": null, + "run_type": "PBESol", + "task_type": "Structure Optimization", + "calc_type": "PBESol Structure Optimization" + }, + ] +``` + +There is some redundancy in the information stored in `input`, `output`, and `calcs_reversed`, but this is by design. +`input` and `output` capture summary information about the first and last steps of the `Job`, whereas +`calcs_reversed` records practically every detail of all the intermediate steps. + + +```{note} +The `TaskDoc` `calcs_reversed` section is designed to capture **all the information that can be obtained from a VASP OUTCAR** +(or `vasprun.xml`). Therefore, if you query your output data from the `atomate2` database, you should not need to +manually look up anything from the OUTCAR. Chances are very good that the information is available somewhere in the +`TaskDoc`. For example: + - you can get the electronic energy of the last SCF iteration (index `[-1]`) of the first +ionic step (index `[0]`) in `calcs_reversed[0].output.ionic_steps[0].electronic_steps[0].e_fr_energy`. + - you can retrieve any INCAR parameter, such as ENCUT, from `calcs_reversed[0].input.incar["ENCUT"]` +``` + +## `emmet` + +### Materials Project and Community document models + +Most document models used by `atomate2` "live" in a separate package called [`emmet`](https://github.com/materialsproject/emmet) +(or more specifically, `emmet-core`), which is installed by default as a dependency of `atomate2`. In general, +mature document models that are used in the Materials Project website or database are developed in `emmet`, +whereas some document models that are more niche or are in earlier stages of development may exist +in `atomate2` itself. + +Here is a partial listing of the codes and calculation types currently supported in `emmet-core`: + +Software: + - VASP + - Q-Chem + - FEFF + - OpenMM + +Calculation Types: + - Structure optimization + - Static / single point energy + - Frequency + - Band structure + - Elastic tensor + +### Code-agnostic document models for analysis + +So far, we have introduced Document Models as a way of parsing input and output data from a specific +calculation software (VASP). However, document models are also useful for capturing data from +"downstream" analysis that is not dependent on the specific code used to generate the data. +Hence, **many document models in `emmet-core` are agnostic or independent of the specific software +used in the initial calculation**. + +To take a simple example, `emmet-core` contains a schema called [`ElectronicStructureSummaryData`](https://github.com/materialsproject/emmet/blob/main/emmet-core/emmet/core/electronic_structure.py#L86) that stores +the `band_gap`, conduction band minimum (`cbm`), valence band maximum (`vbm`), and Fermi level (`e_fermi`): + +```python +class ElectronicStructureBaseData(BaseModel): + task_id: MPID = Field( + ..., + description="The source calculation (task) ID for the electronic structure data. " + "This has the same form as a Materials Project ID.", + ) + + band_gap: float = Field(..., description="Band gap energy in eV.") + + cbm: Optional[Union[float, Dict]] = Field( + None, description="Conduction band minimum data." + ) + + vbm: Optional[Union[float, Dict]] = Field( + None, description="Valence band maximum data." + ) + + efermi: Optional[float] = Field(None, description="Fermi energy in eV.") +``` + +Clearly, this simple document model could be used to store output from any periodic DFT code. + +### Builders + +`emmet-core` also defines `Builder` classes, which take raw calculation results (e.g., the `TaskDoc`) +from our example, perform some analysis or transformation, and then create new document models +in additional `Store`. This paradigm makes it possible to construct automated data processing +pipelines, and is the basis for how the Materials Project database. For more about how builders and +stores work together, see the [`maggma` documentation](https://materialsproject.github.io/maggma/concepts/). + +## Conclusion + +In this tutorial, you learned that `atomate2` uses schema or "Document Models" (based on `pydantic.BaseModel`) +to structure and validate output data. You examined the typical structure of a calculation output by +looking at the schema for a VASP structure optimization (`TaskDoc`). You also learned that `emmet` serves as +a "library" of mature document models used by the Materials Project. + +At this point, you might: + +* Explore how to query results from the docs store: [maggma tutorial](https://materialsproject.github.io/maggma/getting_started/query_101/) +* Learn how to create automatic processing pipelines with `Builder` [maggma tutorial](https://materialsproject.github.io/maggma/getting_started/simple_builder/). diff --git a/docs/user/install.md b/docs/user/install.md index 9a209fcac3..f569ef3241 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -456,6 +456,8 @@ See the following pages for more information on the topics we covered here: - To see how to run and customize the existing Workflows in atomate2, try the [](running_workflows) tutorial (suggested next step). +- To learn more about `TaskDocument` and how `atomate2` organizes output data, review + the [Introduction to task documents, schemas, and emmet](docs_schemas_emmet.md) tutorial. - To see how to manage and execute many workflows at once, try the [](atomate2_fireWorks) tutorial. diff --git a/docs/user/running-workflows.md b/docs/user/running-workflows.md index 28322571af..149b74ea7a 100644 --- a/docs/user/running-workflows.md +++ b/docs/user/running-workflows.md @@ -170,5 +170,6 @@ At this point, you might: * Learn how to chain workflows together: [](connecting_vasp_jobs). * Learn how to customise VASP input settings: [](modifying_input_sets). +* Learn more about [Document Models and Schemas](docs_schemas_emmet) * Configure atomate2 with FireWorks to manage and execute many workflows at once: [](atomate2_fireWorks).