diff --git a/CHANGES.rst b/CHANGES.rst index 91e12e3d35b..97eadc6e96f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,28 @@ Change log ========== +v3.0.0 +------ +* Pymatgen is now completely Python 2.7 and Python 3.x compatible! +* Spglib and pyhull have been updated to support Python 3.x. +* Completely rewritten pure python cifio module (courtesy of William Davidson + Richards) removed dependency on PyCIFRW, which has been causing many issues + with installation. +* Structure and Molecule now supports a very convenient to() and from_str and + from_file functionality. Instead of trying to load the appropriate parser, + you can output and read from the appropriate formats directly. See example + usage. +* ~50% speedup to LinearAssignment code. +* Continuous integration and contribution guidelines now include Python 3. +* **Backwards incompatible changes** +* matgenie.py has now been renamed simply "pmg" for brevity. +* All deprecated methods in pymatgen 2.x have been removed. E.g., + pymatgen.core.structure_modifier is no longer available. +* Pymatgen classes now uses the as_dict() method protocol implemented in the + Monty package. The to_dict property is now deprecated and will be removed + in pymatgen v3.1. +* Update main docs page examples with the new Structure to, from formats. + v2.10.6 ------- * Bug fix for np1.9 incompatibility. Now works. diff --git a/docs/_static/Basic functionality.html b/docs/_static/Basic functionality.html index 2f79442646c..16c5394c587 100644 --- a/docs/_static/Basic functionality.html +++ b/docs/_static/Basic functionality.html @@ -1737,9 +1737,9 @@

Basic Element, Specie and 
si = mg.Element("Si")
-print "Atomic mass of Si is {}".format(si.atomic_mass)
-print "Si has a melting point of {}".format(si.melting_point)
-print "Ionic radii for Si: {}".format(si.ionic_radii)
+print("Atomic mass of Si is {}".format(si.atomic_mass))
+print("Si has a melting point of {}".format(si.melting_point))
+print("Ionic radii for Si: {}".format(si.ionic_radii))
@@ -1781,7 +1781,7 @@

Basic Element, Specie and

-
print "Atomic mass of Si in kg: {}".format(si.atomic_mass.to("kg"))
+
print("Atomic mass of Si in kg: {}".format(si.atomic_mass.to("kg")))
@@ -1822,8 +1822,8 @@

Basic Element, Specie and 
fe2 = mg.Specie("Fe", 2)
-print fe2.atomic_mass
-print fe2.ionic_radius
+print(fe2.atomic_mass)
+print(fe2.ionic_radius)
@@ -1865,10 +1865,10 @@

Basic Element, Specie and 
comp = mg.Composition("Fe2O3")
-print "Weight of Fe2O3 is {}".format(comp.weight)
-print "Amount of Fe in Fe2O3 is {}".format(comp["Fe"])
-print "Atomic fraction of Fe is {}".format(comp.get_atomic_fraction("Fe"))
-print "Weight fraction of Fe is {}".format(comp.get_wt_fraction("Fe"))
+print("Weight of Fe2O3 is {}".format(comp.weight))
+print("Amount of Fe in Fe2O3 is {}".format(comp["Fe"]))
+print("Atomic fraction of Fe is {}".format(comp.get_atomic_fraction("Fe")))
+print("Weight fraction of Fe is {}".format(comp.get_wt_fraction("Fe")))
@@ -1923,7 +1923,7 @@

Lattice & Structure objects 
# Creates cubic Lattice with lattice parameter 4.2
 lattice = mg.Lattice.cubic(4.2)
-print lattice.lengths_and_angles
+print(lattice.lengths_and_angles)

@@ -1964,8 +1964,8 @@

Lattice & Structure objects 
structure = mg.Structure(lattice, ["Cs", "Cl"], [[0, 0, 0], [0.5, 0.5, 0.5]])
-print "Unit cell vol = {}".format(structure.volume)
-print "First site of the structure is {}".format(structure[0])
+print("Unit cell vol = {}".format(structure.volume))
+print("First site of the structure is {}".format(structure[0]))
@@ -2012,7 +2012,7 @@

Lattice & Structure objectsstructure[-1] = "Li" #Change the last added atom to Li. structure[0] = "Cs", [0.01, 0.5, 0] #Shift the first atom by 0.01 in fractional coordinates in the x-direction. immutable_structure = mg.IStructure.from_sites(structure) #Create an immutable structure (cannot be modified). -print immutable_structure +print(immutable_structure)

@@ -2077,7 +2077,7 @@

Basic analyses
#Determining the symmetry
 from pymatgen.symmetry.finder import SymmetryFinder
 finder = SymmetryFinder(structure)
-print "The spacegroup is {}".format(finder.get_spacegroup_symbol())
+print("The spacegroup is {}".format(finder.get_spacegroup_symbol()))

@@ -2122,7 +2122,7 @@

Basic analysess1 = mg.Structure(lattice, ["Cs", "Cl"], [[0, 0, 0], [0.5, 0.5, 0.5]]) s2 = mg.Structure(mg.Lattice.cubic(5), ["Rb", "F"], [[0, 0, 0], [0.5, 0.5, 0.5]]) m = StructureMatcher() -print m.fit_anonymous(s1, s2) #Returns a mapping which maps s1 and s2 onto each other. Strict element fitting is also available. +print(m.fit_anonymous(s1, s2)) #Returns a mapping which maps s1 and s2 onto each other. Strict element fitting is also available. @@ -2136,7 +2136,7 @@

Basic analyses
-{Comp: Cl1: Comp: F1, Comp: Cs1: Comp: Rb1}
+True
@@ -2173,11 +2173,95 @@

Input/output&# 
#Convenient IO to various formats. Format is intelligently determined from file name and extension.
-mg.write_structure(structure, "POSCAR")
-mg.write_structure(structure, "CsCl.cif")
+structure.to(filename="POSCAR")
+structure.to(filename="CsCl.cif")
 
-#Reading a structure from a file.
-structure = mg.read_structure("POSCAR")
+#Or if you just supply fmt, you simply get a string.
+print(structure.to(fmt="poscar"))
+print(structure.to(fmt="cif"))
+
+ +
+
+ + +
+
+ + +
+
+
+Cs3 Li1 Cl4
+1.0
+8.400000 0.000000 0.000000
+0.000000 8.400000 0.000000
+0.000000 0.000000 4.200000
+Cs Cl Li
+3 4 1
+direct
+0.010000 0.500000 0.000000 Cs
+0.500000 0.000000 0.000000 Cs
+0.500000 0.500000 0.000000 Cs
+0.250000 0.250000 0.500000 Cl
+0.250000 0.750000 0.500000 Cl
+0.750000 0.250000 0.500000 Cl
+0.750000 0.750000 0.500000 Cl
+0.000000 0.000000 0.000000 Li
+
+#generated using pymatgen
+data_Cs3LiCl4
+_symmetry_space_group_name_H-M   'P 1'
+_cell_length_a   8.40000000
+_cell_length_b   8.40000000
+_cell_length_c   4.20000000
+_cell_angle_alpha   90.00000000
+_cell_angle_beta   90.00000000
+_cell_angle_gamma   90.00000000
+_symmetry_Int_Tables_number   1
+_chemical_formula_structural   Cs3LiCl4
+_chemical_formula_sum   'Cs3 Li1 Cl4'
+_cell_volume   296.352
+_cell_formula_units_Z   1
+loop_
+ _symmetry_equiv_pos_site_id
+ _symmetry_equiv_pos_as_xyz
+  1  'x, y, z'
+loop_
+ _atom_site_type_symbol
+ _atom_site_label
+ _atom_site_symmetry_multiplicity
+ _atom_site_fract_x
+ _atom_site_fract_y
+ _atom_site_fract_z
+ _atom_site_occupancy
+  Cs  Cs1  1  0.010000  0.500000  0.000000  1
+  Cs  Cs2  1  0.500000  0.000000  0.000000  1
+  Cs  Cs3  1  0.500000  0.500000  0.000000  1
+  Cl  Cl4  1  0.250000  0.250000  0.500000  1
+  Cl  Cl5  1  0.250000  0.750000  0.500000  1
+  Cl  Cl6  1  0.750000  0.250000  0.500000  1
+  Cl  Cl7  1  0.750000  0.750000  0.500000  1
+  Li  Li8  1  0.000000  0.000000  0.000000  1
+
+
+
+
+
+ +
+
+ + +
+
+
+In [12]: +
+
+
+
#Reading a structure from a file.
+structure = mg.Structure.from_file("POSCAR")
@@ -2197,7 +2281,7 @@

Input/output&#
-In [12]: +In [13]:
diff --git a/docs/_static/Molecule.html b/docs/_static/Molecule.html index b2355335b4f..ef81717b9db 100644 --- a/docs/_static/Molecule.html +++ b/docs/_static/Molecule.html @@ -1719,7 +1719,7 @@

Molecules< [-0.513360, -0.889165, -0.363000], [-0.513360, 0.889165, -0.363000]] mol = Molecule(["C", "H", "H", "H", "H"], coords) -print mol +print(mol)

@@ -1759,8 +1759,8 @@

Molecules< 
# A Molecule is simply a list of Sites.
-print mol[0]
-print mol[1]
+print(mol[0])
+print(mol[1])
@@ -1794,7 +1794,7 @@

Molecules< 
# Break a Molecule into two by breaking a bond.
 for frag in mol.break_bond(0, 1):
-    print frag
+    print(frag)
@@ -1838,7 +1838,7 @@

Molecules< 
# Getting neighbors that are within 3 angstroms from C atom.
-print mol.get_neighbors(mol[0], 3)
+print(mol.get_neighbors(mol[0], 3))
@@ -1870,7 +1870,7 @@

Molecules< 
#Detecting bonds
-print mol.get_covalent_bonds()
+print(mol.get_covalent_bonds())
@@ -1904,7 +1904,7 @@

Molecules< 
# If you need to run the molecule in a box with a periodic boundary condition
 # code, you can generate the boxed structure as follows (in a 10Ax10Ax10A box)
 structure = mol.get_boxed_structure(10, 10, 10)
-print structure
+print(structure)

@@ -1987,9 +1987,9 @@

Openbabel interface# Create a pybel.Molecule, which simplifies a lot of access pm = pb.Molecule(a.openbabel_mol) # Print canonical SMILES representation (unique and comparable). -print "Canonical SMILES = {}".format(pm.write("can")) +print("Canonical SMILES = {}".format(pm.write("can"))) # Print Inchi representation -print "Inchi= {}".format(pm.write("inchi")) +print("Inchi= {}".format(pm.write("inchi"))) # pb.outformats provides a listing of available formats. # Let's do a write to the commonly used PDB file. pm.write("pdb", filename="methane.pdb", overwrite=True) @@ -2096,7 +2096,7 @@

Input/Output&#

-

Pymatgen has built-in support for Gaussian and Nwchem, two commonly used computational chemistry programs.

+

Pymatgen has built-in support for the XYZ and Gaussian, NWchem file formats. It also has support for most other file formats if you have openbabel with Python bindings installed.

@@ -2105,6 +2105,107 @@

Input/Output&#
In [10]:
+
+
+
print(mol.to(fmt="xyz"))
+print(mol.to(fmt="g09"))
+print(mol.to(fmt="pdb")) #Needs Openbabel.
+
+mol.to(filename="methane.xyz")
+mol.to(filename="methane.pdb") #Needs Openbabel.
+
+print(Molecule.from_file("methane.pdb"))
+
+ +
+
+

+ +
+
+ + +
+
+
+5
+H4 C1
+C 0.000000 0.000000 0.000000
+H 0.000000 0.000000 1.089000
+H 1.026719 0.000000 -0.363000
+H -0.513360 -0.889165 -0.363000
+H -0.513360 0.889165 -0.363000
+#P HF/6-31G(d)  Test
+
+H4 C1
+
+0 1
+C
+H 1 B1
+H 1 B2 2 A2
+H 1 B3 2 A3 3 D3
+H 1 B4 2 A4 4 D4
+
+B1=1.089000
+B2=1.089000
+A2=109.471221
+B3=1.089000
+A3=109.471213
+D3=120.000017
+B4=1.089000
+A4=109.471213
+D4=119.999966
+
+
+
+COMPND    UNNAMED
+AUTHOR    GENERATED BY OPEN BABEL 2.3.2
+HETATM    1  C   LIG     1       0.000   0.000   0.000  1.00  0.00           C  
+HETATM    2  H   LIG     1       0.000   0.000   1.089  1.00  0.00           H  
+HETATM    3  H   LIG     1       1.027   0.000  -0.363  1.00  0.00           H  
+HETATM    4  H   LIG     1      -0.513  -0.889  -0.363  1.00  0.00           H  
+HETATM    5  H   LIG     1      -0.513   0.889  -0.363  1.00  0.00           H  
+CONECT    1    3    4    5    2                                       
+CONECT    1                                                           
+CONECT    2    1                                                      
+CONECT    3    1                                                      
+CONECT    4    1                                                      
+CONECT    5    1                                                      
+MASTER        0    0    0    0    0    0    0    0    5    0    5    0
+END
+
+Molecule Summary (H4 C1)
+Reduced Formula: H4C
+Charge = 0, Spin Mult = 1
+Sites (5)
+1 C     0.000000     0.000000     0.000000
+2 H     0.000000     0.000000     1.089000
+3 H     1.027000     0.000000    -0.363000
+4 H    -0.513000    -0.889000    -0.363000
+5 H    -0.513000     0.889000    -0.363000
+
+
+
+
+ +
+
+ +
+
+
+
+
+
+

For more fine-grained control over output, you can use the underlying IO classes Gaussian and Nwchem, two commonly used computational chemistry programs.

+
+
+
+
+
+
+In [11]: +
from pymatgen.io.gaussianio import GaussianInput
@@ -2112,7 +2213,7 @@ 
Input/Output&#
                     functional="B3LYP", basis_set="6-31G(d)", 
                     route_parameters={'Opt': "", "SCF": "Tight"},
                     link0_parameters={"%mem": "1000MW"})
-print gau
+print(gau)
@@ -2162,7 +2263,7 @@

Input/Output&#
-In [11]: +In [12]:
@@ -2177,7 +2278,7 @@

Input/Output&# basis_set="6-311G"), ] nwi = NwInput(mol, tasks, geometry_options=["units", "angstroms"]) -print nwi +print(nwi)

@@ -2202,36 +2303,36 @@

Input/Output&# title "H4C1 dft optimize" charge 0 basis - H library "6-31G" C library "6-31G" + H library "6-31G" end dft - xc b3lyp mult 1 + xc b3lyp end task dft optimize title "H4C1 dft freq" charge 0 basis - H library "6-31G" C library "6-31G" + H library "6-31G" end dft - xc b3lyp mult 1 + xc b3lyp end task dft freq title "H4C1 dft energy" charge 0 basis - H library "6-311G" C library "6-311G" + H library "6-311G" end dft - xc b3lyp mult 1 + xc b3lyp end task dft energy diff --git a/docs/change_log.rst b/docs/change_log.rst index 91e12e3d35b..97eadc6e96f 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -1,6 +1,28 @@ Change log ========== +v3.0.0 +------ +* Pymatgen is now completely Python 2.7 and Python 3.x compatible! +* Spglib and pyhull have been updated to support Python 3.x. +* Completely rewritten pure python cifio module (courtesy of William Davidson + Richards) removed dependency on PyCIFRW, which has been causing many issues + with installation. +* Structure and Molecule now supports a very convenient to() and from_str and + from_file functionality. Instead of trying to load the appropriate parser, + you can output and read from the appropriate formats directly. See example + usage. +* ~50% speedup to LinearAssignment code. +* Continuous integration and contribution guidelines now include Python 3. +* **Backwards incompatible changes** +* matgenie.py has now been renamed simply "pmg" for brevity. +* All deprecated methods in pymatgen 2.x have been removed. E.g., + pymatgen.core.structure_modifier is no longer available. +* Pymatgen classes now uses the as_dict() method protocol implemented in the + Monty package. The to_dict property is now deprecated and will be removed + in pymatgen v3.1. +* Update main docs page examples with the new Structure to, from formats. + v2.10.6 ------- * Bug fix for np1.9 incompatibility. Now works. diff --git a/docs/contributing.rst b/docs/contributing.rst index b79292affef..f41e51a75fe 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -92,12 +92,17 @@ following must be satisfied for your contributions to be accepted into pymatgen. We allow a few exceptions when they are well-justified (e.g., Element's atomic number is given a variable name of capital Z, in line with accepted scientific convention), but generally, PEP 8 must be observed. -3. **Documentation** required for all modules, classes and methods. In +3. **Python 3**. All code should seamless work with Python 2.7 and Python 3.x. + Please read Python's official guidelines on how to write Python 3.x + compatible code, including the usage of the "six" package. It is recommended + that you install the "python-modernize" package and run it before submitting + any pull requests. +4. **Documentation** required for all modules, classes and methods. In particular, the method docstrings should make clear the arguments expected and the return values. For complex algorithms (e.g., an Ewald summation), a summary of the alogirthm should be provided, and preferably with a link to a publication outlining the method in detail. -4. **IDE**. We highly recommend the use of Eclipse + PyDev or PyCharm. You +5. **IDE**. We highly recommend the use of Eclipse + PyDev or PyCharm. You should also set up pylint and pep8 and turn those on within the Eclipse PyDev setup. This will warn of any issues with coding styles. diff --git a/docs/index.rst b/docs/index.rst index 1c69e8db774..b0ae656c623 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -337,8 +337,8 @@ API documentation For detailed documentation of all modules and classes, please refer to the :doc:`API docs `. -matgenie.py - Command line tool -------------------------------- +pmg - Command line tool +----------------------- To demonstrate the capabilities of pymatgen and to make it easy for users to quickly use the functionality, pymatgen comes with a set of useful scripts @@ -347,11 +347,11 @@ installed to your path by default when you install pymatgen through the typical installation routes. Here, we will discuss the most versatile of these scripts, known as -matgenie.py. The typical usage of matgenie.py is:: +pmg. The typical usage of pmg is:: - matgenie.py {analyze, plotdos, plotchgint, convert, symm, view, compare} additional_arguments + pmg {analyze, plotdos, plotchgint, convert, symm, view, compare} additional_arguments -At any time, you can use ``"matgenie.py --help"`` or ``"matgenie.py subcommand +At any time, you can use ``"pmg --help"`` or ``"pmg subcommand --help"`` to bring up a useful help message on how to use these subcommands. Here are a few examples of typical usages:: @@ -359,34 +359,34 @@ Here are a few examples of typical usages:: #information. Saves the data in a file called vasp_data.gz for subsequent #reuse. - matgenie.py analyze . + pmg analyze . #Plot the dos from the vasprun.xml file. - matgenie.py plotdos vasprun.xml + pmg plotdos vasprun.xml #Convert between file formats. The script attempts to intelligently #determine the file type. Input file types supported include CIF, #vasprun.xml, POSCAR, CSSR. You can force the script to assume certain file - #types by specifying additional arguments. See matgenie.py convert -h. + #types by specifying additional arguments. See pmg convert -h. - matgenie.py convert input_filename output_filename. + pmg convert input_filename output_filename. #Obtain spacegroup information. - matgenie.py symm -s filename1 filename2 + pmg symm -s filename1 filename2 #Visualize a structure. Requires VTK to be installed. - matgenie.py view filename + pmg view filename #Compare two structures for similarity - matgenie.py compare filename1 filename2 + pmg compare filename1 filename2 #Generate a POTCAR with symbols Li_sv O and the PBE functional - matgenie.py generate --potcar Li_sv O --functional PBE + pmg generate --potcar Li_sv O --functional PBE ipmg - A Custom ipython shell ----------------------------- diff --git a/docs/latest_changes.rst b/docs/latest_changes.rst index b1908228e9d..f3ba8932b8d 100644 --- a/docs/latest_changes.rst +++ b/docs/latest_changes.rst @@ -1,10 +1,24 @@ Change log ========== -v2.10.6 -------- -* Bug fix for np1.9 incompatibility. Now works. -* Use wheel for pymatgen deployments. -* matgenie.py is now renamed to pmg for faster CLI usage. -* Improvements to KPOINTS automatic generation. -* Simpler and faster Structure.get_all_neighbors +v3.0.0 +------ +* Pymatgen is now completely Python 2.7 and Python 3.x compatible! +* Spglib and pyhull have been updated to support Python 3.x. +* Completely rewritten pure python cifio module (courtesy of William Davidson + Richards) removed dependency on PyCIFRW, which has been causing many issues + with installation. +* Structure and Molecule now supports a very convenient to() and from_str and + from_file functionality. Instead of trying to load the appropriate parser, + you can output and read from the appropriate formats directly. See example + usage. +* ~50% speedup to LinearAssignment code. +* Continuous integration and contribution guidelines now include Python 3. +* **Backwards incompatible changes** +* matgenie.py has now been renamed simply "pmg" for brevity. +* All deprecated methods in pymatgen 2.x have been removed. E.g., + pymatgen.core.structure_modifier is no longer available. +* Pymatgen classes now uses the as_dict() method protocol implemented in the + Monty package. The to_dict property is now deprecated and will be removed + in pymatgen v3.1. +* Update main docs page examples with the new Structure to, from formats. diff --git a/docs/pymatgen.analysis.pourbaix.rst b/docs/pymatgen.analysis.pourbaix.rst index 2cfe48735d2..0676e9b051a 100644 --- a/docs/pymatgen.analysis.pourbaix.rst +++ b/docs/pymatgen.analysis.pourbaix.rst @@ -1,6 +1,12 @@ pymatgen.analysis.pourbaix package ================================== +Subpackages +----------- + +.. toctree:: + + Submodules ---------- diff --git a/docs/pymatgen.core.rst b/docs/pymatgen.core.rst index 46941d9765e..0b2d13d88d5 100644 --- a/docs/pymatgen.core.rst +++ b/docs/pymatgen.core.rst @@ -90,14 +90,6 @@ pymatgen.core.structure module :undoc-members: :show-inheritance: -pymatgen.core.structure_modifier module ---------------------------------------- - -.. automodule:: pymatgen.core.structure_modifier - :members: - :undoc-members: - :show-inheritance: - pymatgen.core.surface module ---------------------------- diff --git a/pymatgen/__init__.py b/pymatgen/__init__.py index 3e61dbfaa9b..c281b8224ad 100644 --- a/pymatgen/__init__.py +++ b/pymatgen/__init__.py @@ -3,7 +3,7 @@ "Sai Jayaraman", "Michael Kocher", "Dan Gunter", "Shreyas Cholia", "Vincent L Chevrier", "Rickard Armiento"]) -__date__ = "Sep 10 2014" +__date__ = "Sep 12 2014" __version__ = "3.0.0" #Useful aliases for commonly used objects and modules.