Cache `Lattice` property (`lengths/angles/volume`) for much faster `Structure.as_dict` by DanielYang59 · Pull Request #4421 · materialsproject/pymatgen

DanielYang59 · 2025-05-29T16:57:04Z

Summary

lengths/angles/volume of Lattice would now be cached, related to orjson for much faster JSON operations? #4385

verbosity in as_dict of PeriodicSite/Lattice now explicitly requires literal 0 or 1 to be consistent with docstring, instead of checking if verbosity > 0 (currently in grace period, only warning issued)

pymatgen/src/pymatgen/core/lattice.py

Lines 904 to 905 in 34608d0

    
                       verbosity (int): Default of 0 only includes the matrix representation. 
        
                           Set to 1 to include the lattice parameters.

Cache frequently used `Lattice` properties

Currently length/angles/volume is not cached and is frequently used, for example accessing all lattice parameter related property would lead to length/angles being repeatedly calculated:

pymatgen/src/pymatgen/core/lattice.py

Lines 475 to 524 in 34608d0

    
           @property 
        
           def a(self) -> float: 
        
               """*a* lattice parameter.""" 
        
               return self.lengths[0] 
        
           @property 
        
           def b(self) -> float: 
        
               """*b* lattice parameter.""" 
        
               return self.lengths[1] 
        
           @property 
        
           def c(self) -> float: 
        
               """*c* lattice parameter.""" 
        
               return self.lengths[2] 
        
           @property 
        
           def abc(self) -> tuple[float, float, float]: 
        
               """Lengths of the lattice vectors, i.e. (a, b, c).""" 
        
               return self.lengths 
        
           @property 
        
           def alpha(self) -> float: 
        
               """Angle alpha of lattice in degrees.""" 
        
               return self.angles[0] 
        
           @property 
        
           def beta(self) -> float: 
        
               """Angle beta of lattice in degrees.""" 
        
               return self.angles[1] 
        
           @property 
        
           def gamma(self) -> float: 
        
               """Angle gamma of lattice in degrees.""" 
        
               return self.angles[2] 
        
           @property 
        
           def volume(self) -> float: 
        
               """Volume of the unit cell in Angstrom^3.""" 
        
               matrix = self._matrix 
        
               return float(abs(np.dot(np.cross(matrix[0], matrix[1]), matrix[2]))) 
        
           @property 
        
           def parameters(self) -> tuple[float, float, float, float, float, float]: 
        
               """6-tuple of floats (a, b, c, alpha, beta, gamma).""" 
        
               return (*self.lengths, *self.angles) 
        
           @property 
        
           def params_dict(self) -> dict[str, float]: 
        
               """Dictionary of lattice parameters.""" 
        
               return dict(zip("a b c alpha beta gamma".split(), self.parameters, strict=True))

structure.as_dict now around 8x faster

Before (1000 structure, each has 10-100 atoms):

Total time: 3.29617 s
File: create_dummp_json_structure.py
Function: generate_and_save_structures at line 34

Line #      Hits         Time  Per Hit   % Time  Line Contents
==============================================================
    34                                           @profile
    35                                           def generate_and_save_structures(n, output_dir):
    36         1         20.0     20.0      0.0      os.makedirs(output_dir, exist_ok=True)
    37                                           
    38      1001        222.0      0.2      0.0      for i in range(n):
    39      1000     291789.0    291.8      8.9          structure = generate_dummy_structure()
    40      1000        583.0      0.6      0.0          filename = f"structure_{i:04d}.json.gz"
    41      1000       1942.0      1.9      0.1          filepath = os.path.join(output_dir, filename)
    42                                           
    43      2000     224549.0    112.3      6.8          with gzip.open(filepath, "wb") as f:
    44      1000    2761900.0   2761.9     83.8              dct = structure.as_dict()
    45      1000      15163.0     15.2      0.5              f.write(orjson.dumps(dct))

Now:

Total time: 0.949622 s
File: create_dummp_json_structure.py
Function: generate_and_save_structures at line 34

Line #      Hits         Time  Per Hit   % Time  Line Contents
==============================================================
    34                                           @profile
    35                                           def generate_and_save_structures(n, output_dir):
    36         1         37.0     37.0      0.0      os.makedirs(output_dir, exist_ok=True)
    37                                           
    38      1001        195.0      0.2      0.0      for i in range(n):
    39      1000     286696.0    286.7     30.2          structure = generate_dummy_structure()
    40      1000        511.0      0.5      0.1          filename = f"structure_{i:04d}.json.gz"
    41      1000       1843.0      1.8      0.2          filepath = os.path.join(output_dir, filename)
    42                                           
    43      2000     214130.0    107.1     22.5          with gzip.open(filepath, "wb") as f:
    44      1000     431677.0    431.7     45.5              dct = structure.as_dict()
    45      1000      14533.0     14.5      1.5              f.write(orjson.dumps(dct))

Also note lattice (the performance bottleneck) is not used in the dict for site:

pymatgen/src/pymatgen/core/structure.py

Lines 2856 to 2857 in 34608d0

    
           site_dict = site.as_dict(verbosity=verbosity) 
        
           del site_dict["lattice"]

So we could modify as_dict to control whether lattice would be generated at all

This could reduce the runtime slightly so I guess it's not worth the effort:

Total time: 0.867376 s

shyuep · 2025-05-30T13:52:02Z

There is no need to put in a setter. The Lattice object is meant to be immutable like. There is no setter today and you cannot modify a matrix (without some weird hacky code like modifying variables indicated as private by convention).

DanielYang59 · 2025-05-30T14:37:30Z

Good point! having matrix immutable makes caching much easier :), I didn't realize that

verbosity narrow down to 0 or 1

88c74d8

DanielYang59 changed the title ~~Cache lattice property~~ Cache Lattice property: lengths/angles/volume May 29, 2025

cache frequently used lattice property

108fee6

DanielYang59 force-pushed the cache-lattice-property branch from 3f11e41 to 108fee6 Compare May 29, 2025 17:00

DanielYang59 added 4 commits May 29, 2025 19:05

lint fix

64e1b56

use cached lengths over abc

9a82414

numpy api is much faster

b53b610

tweak docstring

b8abefd

DanielYang59 changed the title ~~Cache Lattice property: lengths/angles/volume~~ Cache Lattice property (lengths/angles/volume) for much faster Structure.as_dict May 29, 2025

add test for cached property invalidation

0e97566

DanielYang59 marked this pull request as ready for review May 30, 2025 09:44

DanielYang59 requested review from mkhorton and shyuep as code owners May 30, 2025 09:44

remove matrix setter

3e37b11

shyuep merged commit 005613c into materialsproject:master May 30, 2025
43 checks passed

DanielYang59 deleted the cache-lattice-property branch May 30, 2025 15:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cache `Lattice` property (`lengths/angles/volume`) for much faster `Structure.as_dict`#4421

Cache `Lattice` property (`lengths/angles/volume`) for much faster `Structure.as_dict`#4421
shyuep merged 8 commits intomaterialsproject:masterfrom
DanielYang59:cache-lattice-property

DanielYang59 commented May 29, 2025 •

edited

Loading

Uh oh!

shyuep commented May 30, 2025

Uh oh!

DanielYang59 commented May 30, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	verbosity (int): Default of 0 only includes the matrix representation.
	Set to 1 to include the lattice parameters.

	@property
	def a(self) -> float:
	"""a lattice parameter."""
	return self.lengths[0]

	@property
	def b(self) -> float:
	"""b lattice parameter."""
	return self.lengths[1]

	@property
	def c(self) -> float:
	"""c lattice parameter."""
	return self.lengths[2]

	@property
	def abc(self) -> tuple[float, float, float]:
	"""Lengths of the lattice vectors, i.e. (a, b, c)."""
	return self.lengths

	@property
	def alpha(self) -> float:
	"""Angle alpha of lattice in degrees."""
	return self.angles[0]

	@property
	def beta(self) -> float:
	"""Angle beta of lattice in degrees."""
	return self.angles[1]

	@property
	def gamma(self) -> float:
	"""Angle gamma of lattice in degrees."""
	return self.angles[2]

	@property
	def volume(self) -> float:
	"""Volume of the unit cell in Angstrom^3."""
	matrix = self._matrix
	return float(abs(np.dot(np.cross(matrix[0], matrix[1]), matrix[2])))

	@property
	def parameters(self) -> tuple[float, float, float, float, float, float]:
	"""6-tuple of floats (a, b, c, alpha, beta, gamma)."""
	return (self.lengths, self.angles)

	@property
	def params_dict(self) -> dict[str, float]:
	"""Dictionary of lattice parameters."""
	return dict(zip("a b c alpha beta gamma".split(), self.parameters, strict=True))

	site_dict = site.as_dict(verbosity=verbosity)
	del site_dict["lattice"]

Conversation

DanielYang59 commented May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Cache frequently used Lattice properties

Uh oh!

shyuep commented May 30, 2025

Uh oh!

DanielYang59 commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DanielYang59 commented May 29, 2025 •

edited

Loading

Cache frequently used `Lattice` properties

DanielYang59 commented May 30, 2025 •

edited

Loading