Add telemetry

.gitignore

@@ -46,7 +46,6 @@ input/*
 
 # simulation outputs
 out/
-config.py
 matplotlibrc
 *.pickle
 *.sav

.lycheeignore

@@ -15,3 +15,6 @@ file:///home/runner/work/PyBaMM/PyBaMM/docs/source/user_guide/fundamentals/pybam
 
 # Errors in docs/source/user_guide/index.md
 file:///home/runner/work/PyBaMM/PyBaMM/docs/source/user_guide/api_docs
+
+# Telemetry
+https://us.i.posthog.com

CHANGELOG.md

@@ -1,16 +1,20 @@
 # [Unreleased](https://github.com/pybamm-team/PyBaMM/)
 
 ## Features
+
+- Added basic telemetry to record which functions are being run. See [Telemetry section in the User Guide](https://docs.pybamm.org/en/latest/source/user_guide/index.html#telemetry) for more information. ([#4441](https://github.com/pybamm-team/PyBaMM/pull/4441))
 - Added sensitivity calculation support for `pybamm.Simulation` and `pybamm.Experiment` ([#4415](https://github.com/pybamm-team/PyBaMM/pull/4415))
 
 ## Optimizations
+
 - Removed the `start_step_offset` setting and disabled minimum `dt` warnings for drive cycles with the (`IDAKLUSolver`). ([#4416](https://github.com/pybamm-team/PyBaMM/pull/4416))
 
 ## Features
 
 - Added phase-dependent particle options to LAM #4369
 
 ## Breaking changes
+
 - The parameters "... electrode OCP entropic change [V.K-1]" and "... electrode volume change" are now expected to be functions of stoichiometry only instead of functions of both stoichiometry and maximum concentration ([#4427](https://github.com/pybamm-team/PyBaMM/pull/4427))
 - Renamed `set_events` function to `add_events_from` to better reflect its purpose. ([#4421](https://github.com/pybamm-team/PyBaMM/pull/4421))
 

docs/source/user_guide/index.md

@@ -72,3 +72,12 @@ glob:
 ../examples/notebooks/creating_models/5-half-cell-model.ipynb
 ../examples/notebooks/creating_models/6-a-simple-SEI-model.ipynb
 ```
+
+# Telemetry
+
+PyBaMM collects anonymous usage data to help improve the library. This telemetry is enabled by default but can be easily disabled. Here's what you need to know:
+
+- **What is collected**: Basic usage information like PyBaMM version, Python version, and which functions are run.
+- **Why**: To understand how PyBaMM is used and prioritize development efforts.
+- **Opt-out**: To disable telemetry, set the environment variable `PYBAMM_OPTOUT_TELEMETRY=true` or use `pybamm.telemetry.disable()` in your code.
+- **Privacy**: No personal information (name, email, etc) or sensitive information (parameter values, simulation results, etc) is ever collected.

examples/scripts/compare_lithium_ion.py

@@ -4,6 +4,7 @@
 import pybamm
 
 pybamm.set_logging_level("INFO")
+pybamm.telemetry.disable()
 
 # load models
 models = [

noxfile.py

@@ -63,6 +63,7 @@ def set_iree_state():
     "IREE_INDEX_URL": os.getenv(
         "IREE_INDEX_URL", "https://iree.dev/pip-release-links.html"
     ),
+    "PYBAMM_OPTOUT_TELEMETRY": "true",  # don't capture telemetry in tests
 }
 VENV_DIR = Path("./venv").resolve()
 

pyproject.toml

@@ -44,6 +44,7 @@ dependencies = [
     "typing-extensions>=4.10.0",
     "pandas>=1.5.0",
     "pooch>=1.8.1",
+    "posthog",
 ]
 
 [project.urls]
@@ -280,3 +281,6 @@ module = [
         "pybamm.models.full_battery_models.base_battery_model.*"
         ]
 disable_error_code = "attr-defined"
+
+[tool.poetry.scripts]
+post-install = "scripts.post_install:run"

scripts/post_install.py

@@ -0,0 +1,5 @@
+import pybamm
+
+
+def run():
+    pybamm.config.generate()

src/pybamm/__init__.py

@@ -192,8 +192,8 @@
 # Batch Study
 from .batch_study import BatchStudy
 
-# Callbacks
-from . import callbacks
+# Callbacks, telemetry, config
+from . import callbacks, telemetry, config
 
 # Pybamm Data manager using pooch
 from .pybamm_data import DataLoader
@@ -205,6 +205,7 @@
     "batch_study",
     "callbacks",
     "citations",
+    "config",
     "discretisations",
     "doc_utils",
     "experiment",
@@ -220,6 +221,7 @@
     "simulation",
     "solvers",
     "spatial_methods",
+    "telemetry",
     "type_definitions",
     "util",
     "version",

src/pybamm/config.py

@@ -0,0 +1,85 @@
+import uuid
+import pathlib
+import os
+
+
+def _get_config_file():
+    # Get the home directory
+    home_dir = pathlib.Path.home()
+
+    # Create the file path for pybamm config
+    config_file = home_dir / ".config" / "pybamm" / "config.yml"
+
+    return config_file
+
+
+def is_running_tests():
+    """
+    Detect if the code is being run as part of a test suite.
+
+    Returns:
+        bool: True if running tests, False otherwise.
+    """
+    import sys
+
+    # Check if pytest or unittest is running
+    if any(
+        test_module in sys.modules for test_module in ["pytest", "unittest", "nose"]
+    ):
+        return True
+
+    # Check for GitHub Actions environment variable
+    if "GITHUB_ACTIONS" in os.environ:
+        return True
+
+    # Check for other common CI environment variables
+    ci_env_vars = ["CI", "TRAVIS", "CIRCLECI", "JENKINS_URL", "GITLAB_CI"]
+    if any(var in os.environ for var in ci_env_vars):
+        return True
+
+    # Check for common test runner names in command-line arguments
+    test_runners = ["pytest", "unittest", "nose", "trial", "nox", "tox"]
+    return any(runner in sys.argv[0].lower() for runner in test_runners)
+
+
+def generate():
+    if is_running_tests():
+        return
+
+    # Check if the config file already exists
+    if read() is not None:
+        return
+
+    config_file = _get_config_file()
+
+    # Create the directory if it doesn't exist
+    config_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Generate a UUID
+    unique_id = uuid.uuid4()
+
+    # Write the UUID to the config file in YAML format
+    with open(config_file, "w") as f:
+        f.write("pybamm:\n")
+        f.write(f"  uuid: {unique_id}\n")
+
+
+def read():
+    config_file = _get_config_file()
+
+    # Check if the config file exists
+    if not config_file.exists():
+        return None
+
+    # Read the UUID from the config file
+    with open(config_file) as f:
+        content = f.read().strip()
+
+    # Extract the UUID using YAML parsing
+    try:
+        import yaml
+
+        config = yaml.safe_load(content)
+        return config["pybamm"]
+    except (yaml.YAMLError, ValueError):
+        return None

src/pybamm/simulation.py

@@ -10,6 +10,7 @@
 import warnings
 from functools import lru_cache
 from datetime import timedelta
+import pybamm.telemetry
 from pybamm.util import import_optional_dependency
 
 from pybamm.expression_tree.operations.serialise import Serialise
@@ -450,6 +451,8 @@ def solve(
             Additional key-word arguments passed to `solver.solve`.
             See :meth:`pybamm.BaseSolver.solve`.
         """
+        pybamm.telemetry.capture("simulation-solved")
+
         # Setup
         if solver is None:
             solver = self._solver

src/pybamm/telemetry.py

@@ -0,0 +1,41 @@
+from posthog import Posthog
+import os
+import pybamm
+import sys
+
+_posthog = Posthog(
+    # this is the public, write only API key, so it's ok to include it here
+    project_api_key="phc_bLZKBW03XjgiRhbWnPsnKPr0iw0z03fA6ZZYjxgW7ej",
+    host="https://us.i.posthog.com",
+)
+
+
+def disable():
+    _posthog.disabled = True
+
+
+_opt_out = os.getenv("PYBAMM_OPTOUT_TELEMETRY", "false").lower()
+if _opt_out != "false":
+    disable()
+
+
+def capture(event):
+    # don't capture events in automated testing
+    if pybamm.config.is_running_tests():
+        return
+
+    properties = {
+        "python_version": sys.version,
+        "pybamm_version": pybamm.__version__,
+    }
+
+    config = pybamm.config.read()
+    if config:
+        user_id = config["uuid"]
+    else:
+        user_id = "anonymous-user-id"
+        properties["$process_person_profile"] = False
+
+    # setting $process_person_profile to False mean that we only track what events are
+    # being run and don't capture anything about the user
+    _posthog.capture(user_id, event, properties=properties)