feat(tidy3d): FXC-3294-add-opt-in-local-cache-for-simulation-results

Author: marcorudolphflex

CHANGELOG.md

@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Validation for `run_only` field in component modelers to catch duplicate or invalid matrix indices early with clear error messages.
 - Introduced a profile-based configuration manager with TOML persistence and runtime overrides exposed via `tidy3d.config`.
 - Added support of `os.PathLike` objects as paths like `pathlib.Path` alongside `str` paths in all path-related functions.
+- Added configurable local simulation result caching with checksum validation, eviction limits, and per-call overrides across `web.run`, `web.load`, and job workflows.
 
 ### Changed
 - Improved performance of antenna metrics calculation by utilizing cached wave amplitude calculations instead of recomputing wave amplitudes for each port excitation in the `TerminalComponentModelerData`.

docs/index.rst

@@ -168,6 +168,18 @@ This will produce the following plot, which visualizes the electromagnetic field
 
 You can now postprocess simulation data using the same python session, or view the results of this simulation on our web-based `graphical user interface (GUI) <https://tidy3d.simulation.cloud>`_.
 
+.. admonition:: Caching for repeated simulations
+   :class: tip
+
+   Repeated runs of the same simulation can reuse solver results by enabling the
+   local cache: ``td.config.local_cache.enabled = True``. You may configure the cache directory
+   with ``local_cache.directory``. If the number of entries (``local_cache.max_entries``) or the storage size
+   (``local_cache.max_size_gb``) is exceeded, cache entries are evicted by least-recently-used (LRU) order.
+   You can clear all stored artifacts with ``td.web.cache.clear()``.
+   Additionally, there is server-side caching controlled via ``td.config.web.enable_caching``
+   (enabled by default). While this can avoid recomputation on the server, it still requires
+   upload/download of results which is why we recommend enabling the local cache.
+
 .. `TODO: open example in colab <https://github.com/flexcompute/tidy3d>`_
 
 
@@ -262,4 +274,3 @@ Contents
 
 
 
-

tests/config/conftest.py

@@ -42,7 +42,7 @@ def mock_config_dir(tmp_path, monkeypatch):
 
     base_dir = tmp_path / "config_home"
     monkeypatch.setenv("TIDY3D_BASE_DIR", str(base_dir))
-    return base_dir / ".tidy3d"
+    return base_dir / "config"
 
 
 @pytest.fixture

tests/test_cli/test_migrate.py

@@ -18,7 +18,7 @@ def temp_config_dir(monkeypatch, tmp_path) -> Path:
     original_base = os.environ.get("TIDY3D_BASE_DIR")
     monkeypatch.setenv("TIDY3D_BASE_DIR", str(tmp_path))
     reload_config(profile="default")
-    config_dir = Path(tmp_path) / ".tidy3d"
+    config_dir = Path(tmp_path) / "config"
     config_dir.mkdir(parents=True, exist_ok=True)
     yield config_dir
     if original_base is None:

tests/test_components/autograd/test_autograd.py

@@ -661,7 +661,7 @@ def plot_sim(sim: td.Simulation, plot_eps: bool = True) -> None:
 # args = [("polyslab", "mode")]
 
 
-def get_functions(structure_key: str, monitor_key: str) -> typing.Callable:
+def get_functions(structure_key: str, monitor_key: str) -> dict[str, typing.Callable]:
     if structure_key == ALL_KEY:
         structure_keys = structure_keys_
     else: