Repository files navigation

From v2021.5.13, pymatgen-db is now a proper namespace add-on to pymatgen. Inother words, you no longer import from matgendb but rather pymatgen.db.

The easiest way to install pymatgen-db on any system is to use pip, as follows:

pip install pymatgen-db

A powerful command-line script (mgdb) provides most of the access to many ofthe features in pymatgen-db, including db initialization, insertion of data,running the materials genomics ui, etc. To see all options available, type:

mgdb --help

The first step is to install and setup MongoDB on a server of your choice.TheMongoDB manual is an excellent place to start. For the purposes oftesting out the tools here, you may simply download the binary distributionscorresponding to your OS from theMongoDB website, and then running thefollowing commands::

# For Mac and Linux OS.mkdir test_db&& mongod --dbpath test_db

This will create a test database and start the Mongo daemon. Once you aredone with testing, you can simply press Ctrl-C to stop the server and deletethe "test_db" folder. Running a Mongo server this way is insecure as Mongodoes not enable authentication by default. Please refer to theMongoDB manualwhen setting up your production database.

After your server is up, you should create a database config file by runningthe following command:

mgdb init -c db.json

This will prompt you for a few parameters to create a database config file,which will make it much easier to use mgdb in future. Note that the config filename can be anything of your choice, but using "db.json" will allow you to usemgdb without explicitly specifying the filename in future. If you are justtesting using the test database, simply hit Enter to accept the defaults forall settings.

For more advanced use of the "db.json" config file (e.g., specifying aliases,defaults, etc., please refer to the followingsample <http://pythonhosted.org/pymatgen-db/_static/db.json>_.

To insert an entire directory of runs (where the topmost directory is"dir_name") into the database, use the following command:

# Note that "-c db.json" may be omitted if the config filename is the# current directory under the default filename of db.json.mgdb insert -c db.json dir_name

A sample run has been provided fordownload <http://pythonhosted.org/pymatgen-db/_static/Li2O.zip>_ for testingpurposes. Unzip the file and run the above command in the directory.

Sometimes, more fine-grained querying is needed (e.g., for subsequentpostprocessing and analysis).

The mgdb script allows you to make simple queries from the command line:

# Query for the task id and energy per atom of all calculations with# formula Li2O. Note that the criteria has to be specified in the form of# a json string. Note that "-c db.json" may be omitted if the config# filename is the current directory under the default filename of db.json.mgdb query -c db.json --crit'{"pretty_formula": "Li2O"}' --props task_id energy_per_atom

For more advanced queries, you can use the QueryEngine class for which analias is provided at the root package. Some examples are as follows:

>>>frompymatgen.dbimportQueryEngine# Depending on your db.json, you may need to supply keyword args below# for `port`, `database`, `collection`, etc.>>>qe=QueryEngine()#Print the task id and formula of all entries in the database.>>>forrinqe.query(properties=["pretty_formula","task_id"]):...print"{task_id} - {pretty_formula}".format(**r)...12-Li2O# Get a pymatgen Structure from the task_id.>>>structure=qe.get_structure_from_id(12)# Get pymatgen ComputedEntries using a criteria.>>>entries=qe.get_entries({})

The language follows very closely to pymongo/MongoDB syntax, except thatQueryEngine provides useful aliases for commonly used fields as well astranslation to commonly used pymatgen objects like Structure andComputedEntries.

Currently, pymatgen-db is written with standard VASP runs in mind. However,it is perfectly extensible to any kind of data, e.g., other kinds of VASP runs(bandstructure, NEB, etc.) or just any form of data in general. Developerslooking to adapt pymatgen-db for other purposes should look at theVaspToDbTaskDrone class as an example and write similar drones for theirneeds. The QueryEngine can generally be applied to any Mongo collection,with suitable specification of aliases if desired.

If you use pymatgen and pymatgen-db in your research, please consider citingthe following work:

Shyue Ping Ong, William Davidson Richards, Anubhav Jain, Geoffroy Hautier,Michael Kocher, Shreyas Cholia, Dan Gunter, Vincent Chevrier, Kristin A.Persson, Gerbrand Ceder.*Python Materials Genomics (pymatgen) : A Robust,Open-Source Python Library for Materials Analysis.* ComputationalMaterials Science, 2013, 68, 314-319. `doi:10.1016/j.commatsci.2012.10.028<http://dx.doi.org/10.1016/j.commatsci.2012.10.028>`_