ionworks-api 0.1.0__py3-none-any.whl

ionworks/validators.py

@@ -0,0 +1,171 @@
+"""
+Reusable validator functions and composable pipelines for inbound/outbound value
+normalization (e.g., converting between pandas DataFrames and dictionaries).
+"""
+
+import math
+import pathlib
+from typing import Any, Callable, Iterable
+
+import numpy as np
+import pandas as pd
+import polars as pl
+import pybamm
+from pybamm.expression_tree.operations.serialise import convert_symbol_to_json
+
+# --- Atomic validators ------------------------------------------------------ #
+
+
+def df_to_dict_validator(v: Any) -> Any:
+    """Convert DataFrame to dict with orient='list' for serialization."""
+    if isinstance(v, pd.DataFrame):
+        # Replace NaN with None for JSON compatibility
+        return v.replace(np.nan, None).to_dict(orient="list")
+    elif isinstance(v, pl.DataFrame):
+        # Replace NaN with None for JSON compatibility, then convert to dict
+        return v.fill_nan(None).to_dict(as_series=False)
+    return v
+
+
+def dict_to_df_validator(v: Any) -> Any:
+    """Convert dict to DataFrame for data processing."""
+    if isinstance(v, dict):
+        try:
+            return pd.DataFrame(v)
+        except ValueError as e:
+            if "If using all scalar values, you must pass an index" in str(e):
+                # Handle case where all values are scalars by providing an index
+                return pd.DataFrame(v, index=[0])
+            else:
+                raise
+    return v
+
+
+def parameter_validator(v: Any) -> Any:
+    """Convert pybamm.Symbol values to JSON-serializable form."""
+    if isinstance(v, pybamm.Symbol):
+        return convert_symbol_to_json(v)
+    return v
+
+
+def float_sanitizer(v: Any) -> Any:
+    """Sanitize float values to JSON-compatible forms. Currently removes NaN and
+    infinity values."""
+    if isinstance(v, float):
+        if math.isinf(v):
+            return "Infinity" if v > 0 else "-Infinity"
+        elif np.isnan(v):
+            return None
+    elif isinstance(v, np.floating):
+        if np.isinf(v):
+            return "Infinity" if v > 0 else "-Infinity"
+        elif np.isnan(v):
+            return None
+    return v
+
+
+def bounds_tuple_validator(v: Any) -> Any:
+    """Convert bounds 2-tuple to list for JSON serialization.
+
+    Converts tuples with exactly 2 elements to lists. This is useful for
+    bounds parameters that may be provided as tuples (lower, upper) but
+    need to be serialized as lists.
+
+    Parameters
+    ----------
+    v : Any
+        Value to validate. If it's a tuple with 2 elements, converts to list.
+
+    Returns
+    -------
+    Any
+        List if input was a 2-tuple, otherwise unchanged.
+    """
+    if isinstance(v, tuple) and len(v) == 2:
+        return list(v)
+    return v
+
+
+def file_scheme_validator(v: Any) -> Any:
+    """
+    Convert file:// and folder:// scheme paths to serialized dicts.
+
+    Handles:
+    - "file:" prefixed paths: loads CSV file as dict (serialized)
+    - "folder:" prefixed paths: loads time_series.csv and steps.csv as dict
+    - All other values: returned unchanged
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file or folder path doesn't exist
+    Exception
+        If reading the CSV file fails for any other reason
+    """
+    if isinstance(v, str) and v.startswith("file:"):
+        path = pathlib.Path(v.split(":")[1]).expanduser().resolve()
+        if not path.exists() or not path.is_file():
+            raise FileNotFoundError(f"CSV file not found: {v}")
+        return df_to_dict_validator(pd.read_csv(path))
+    elif isinstance(v, str) and v.startswith("folder:"):
+        path = pathlib.Path(v.split(":")[1]).expanduser().resolve()
+        if not path.exists() or not path.is_dir():
+            raise FileNotFoundError(f"Folder not found: {v}")
+        return {
+            "time_series": df_to_dict_validator(pd.read_csv(path / "time_series.csv")),
+            "steps": df_to_dict_validator(pd.read_csv(path / "steps.csv")),
+        }
+    return v
+
+
+# --- Pipeline composition helpers ------------------------------------------ #
+
+Validator = Callable[[Any], Any]
+
+
+def _apply_pipeline(value: Any, validators: Iterable[Validator]) -> Any:
+    transformed = value
+    for validator in validators:
+        transformed = validator(transformed)
+    return transformed
+
+
+def _apply_recursive(value: Any, validators: Iterable[Validator]) -> Any:
+    if isinstance(value, dict):
+        return {key: _apply_recursive(val, validators) for key, val in value.items()}
+    if isinstance(value, tuple):
+        # Apply validators to tuple first (e.g., to convert bounds tuples to lists)
+        transformed = _apply_pipeline(value, validators)
+        # If validator converted tuple to list, process recursively
+        if isinstance(transformed, list):
+            return [_apply_recursive(item, validators) for item in transformed]
+        # Otherwise, process tuple items recursively
+        return [_apply_recursive(item, validators) for item in transformed]
+    if isinstance(value, list):
+        return [_apply_recursive(item, validators) for item in value]
+    return _apply_pipeline(value, validators)
+
+
+# --- Public pipelines ------------------------------------------------------- #
+
+validators_outbound: list[Validator] = [
+    float_sanitizer,
+    bounds_tuple_validator,
+    file_scheme_validator,
+    df_to_dict_validator,
+    parameter_validator,
+]
+
+validators_inbound: list[Validator] = [
+    dict_to_df_validator,
+]
+
+
+def run_validators_outbound(v: Any) -> Any:
+    """Recursively apply outbound validators to values and nested containers."""
+    return _apply_recursive(v, validators_outbound)
+
+
+def run_validators_inbound(v: Any) -> Any:
+    """Recursively apply inbound validators to values and nested containers."""
+    return _apply_recursive(v, validators_inbound)

ionworks_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: ionworks-api
+Version: 0.1.0
+Summary: Python client for interacting with the Ionworks API
+Requires-Python: >=3.10
+Requires-Dist: black
+Requires-Dist: iwutil
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: polars
+Requires-Dist: pyarrow
+Requires-Dist: pybamm>=25.10.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: python-dotenv==1.2.1
+Requires-Dist: requests==2.32.5
+Requires-Dist: supabase
+Requires-Dist: types-requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ionworks API Client
+
+⚠️ **Warning**: This client is under active development and the API may change without notice.
+
+A Python client for interacting with the Ionworks API.
+
+## Installation
+
+1. Clone this repository
+2. Install the package in editable mode:
+
+```bash
+pip install -e .
+```
+
+3. Get your API key from the [Ionworks account settings](https://app.ionworks.com/dashboard/account) and set it as the `IONWORKS_API_KEY` environment variable (or in a `.env` file).
+
+## Usage
+
+Basic usage example:
+
+```python
+from ionworks import Ionworks
+
+# Initialize client (uses IONWORKS_API_KEY from environment/.env file)
+client = Ionworks()
+
+# or provide credentials directly
+client = Ionworks(api_key="your_key")
+
+# Check API health
+health = client.health_check()
+print(health)
+```
+
+### Uploading data to the Ionworks app
+
+Uploading data to the Ionworks app follows a three-step process:
+
+1. Create a cell spec (or get an existing one)
+2. Create a cell instance with the spec id
+3. Upload measurement(s) with time series data using the instance id
+
+Given time series data, the data can be uploaded as follows:
+
+```python
+from ionworks import Ionworks
+import pandas as pd
+
+client = Ionworks()
+
+# Step 1: Create or get a cell specification
+cell_spec = client.cell_spec.create_or_get(
+    {
+        "name": "NCM622/Graphite Coin Cell",
+        "form_factor": "R2032",
+        "manufacturer": "Custom Cells",
+        "ratings": {
+            "capacity": {"value": 0.002, "unit": "A*h"},
+            "voltage_min": {"value": 2.5, "unit": "V"},
+            "voltage_max": {"value": 4.2, "unit": "V"},
+        },
+        "cathode": {
+            "properties": {"loading": {"value": 12.3, "unit": "mg/cm**2"}},
+            "material": {"name": "NCM622", "manufacturer": "BASF"},
+        },
+        "anode": {
+            "properties": {"loading": {"value": 6.5, "unit": "mg/cm**2"}},
+            "material": {"name": "Graphite", "manufacturer": "Customcells"},
+        },
+    }
+)
+
+# Step 2: Create or get a cell instance
+cell_instance = client.cell_instance.create_or_get(
+    cell_spec.id,
+    {
+        "name": "NCM622-GR-001",
+        "batch": "BATCH-2024-001",
+        "date_manufactured": "2024-01-20",
+        "measured_properties": {
+            "cathode": {"loading": {"value": 12.1, "unit": "mg/cm**2"}},
+            "anode": {"loading": {"value": 6.4, "unit": "mg/cm**2"}},
+        },
+    },
+)
+
+# Step 3: Upload measurement with time series data
+time_series = pd.DataFrame(
+    {
+        "Time [s]": [0, 1, 2, 3, 4, 5],
+        "Voltage [V]": [3.0, 3.2, 3.5, 3.8, 4.0, 4.2],
+        "Current [A]": [0.002, 0.002, 0.002, 0.002, 0.002, 0.002],
+        "Step count": [0, 0, 0, 1, 1, 1],
+        "Cycle count": [0, 0, 0, 0, 0, 0],
+        "Step from cycler": [1, 1, 1, 2, 2, 2],
+        "Cycle from cycler": [0, 0, 0, 0, 0, 0],
+    }
+)
+
+measurement_data = {
+    "measurement": {
+        "name": "Formation Cycle 1",
+        "protocol": {
+            "name": "CC-CV charge at C/10 to 4.2V",
+            "ambient_temperature_degc": 25,
+        },
+        "test_setup": {
+            "cycler": "Biologic VMP3",
+            "operator": "Jane Smith",
+        },
+        "notes": "Formation cycle - first charge",
+    },
+    "time_series": time_series,
+}
+
+measurement_bundle = client.cell_measurement.create(
+    cell_instance.id, measurement_data
+)
+
+print(f"Created measurement: {measurement_bundle.measurement.name}")
+print(f"Steps created: {measurement_bundle.steps_created}")
+```
+
+### Reading cell data
+
+```python
+from ionworks import Ionworks
+
+client = Ionworks()
+
+# List all cell specifications
+specs = client.cell_spec.list()
+for spec in specs[:5]:
+    print(f"  - {spec.name} (form_factor: {spec.form_factor})")
+
+# Get a specific cell spec with full nested data
+full_spec = client.cell_spec.get(spec_id)
+print(f"Capacity: {full_spec.ratings['capacity']['value']} "
+      f"{full_spec.ratings['capacity']['unit']}")
+
+# Get cell instance by slug
+instance = client.cell_instance.get_by_slug("ncm622-gr-001")
+
+# List measurements for an instance
+measurements = client.cell_measurement.list(instance.id)
+
+# Get measurement detail with time series
+measurement_detail = client.cell_measurement.detail(measurement_id)
+print(f"Time series shape: {measurement_detail.time_series.shape}")
+```
+
+### Running pipelines
+
+Pipelines allow you to run complex workflows combining data fitting, calculations, and validations. A pipeline consists of named elements, where each element has an `element_type` and configuration specific to that type.
+
+**Recommended workflow:** First upload your experimental data using the cell measurement API (see "Uploading data to the Ionworks app" above), then reference it in your pipeline using the `db:<measurement_id>` format. This ensures your data is stored and versioned in the database.
+
+Available element types:
+
+- `entry`: Provide initial parameter values
+- `data_fit`: Fit model parameters to experimental data
+- `calculation`: Run calculations (e.g., OCP fitting)
+- `validation`: Validate model against data
+
+```python
+import time
+from ionworks import Ionworks
+
+client = Ionworks()
+
+# First, upload your data (see "Uploading data to the Ionworks app" section)
+# Then get the measurement ID to reference in the pipeline
+measurements = client.cell_measurement.list(cell_instance_id)
+measurement_id = measurements[0].id  # or find the specific measurement you need
+
+# Define entry configuration with initial parameter values
+entry_config = {
+    "values": {
+        "Negative particle diffusivity [m2.s-1]": 3.3e-14,
+        "Positive particle diffusivity [m2.s-1]": 4e-15,
+        # ... other parameters
+    }
+}
+
+# Define datafit configuration - reference uploaded data with db:<measurement_id>
+datafit_config = {
+    "objectives": {
+        "test_1C": {
+            "objective": "CurrentDriven",
+            "model": {"type": "SPMe"},
+            "data": f"db:{measurement_id}",  # Reference data from database
+            "custom_parameters": {"Ambient temperature [K]": "initial_temperature"},
+        },
+    },
+    "parameters": {
+        "Negative particle diffusivity [m2.s-1]": {
+            "bounds": [1e-14, 1e-13],
+            "initial_value": 2e-14,
+        },
+        "Positive particle diffusivity [m2.s-1]": {
+            "bounds": [1e-15, 1e-14],
+            "initial_value": 2e-15,
+        },
+    },
+    "cost": {"type": "RMSE"},
+    "optimizer": {"type": "ScipyDifferentialEvolution"},
+}
+
+# Create pipeline config with named elements
+pipeline_config = {
+    "elements": {
+        "entry": {**entry_config, "element_type": "entry"},
+        "fit data": {**datafit_config, "element_type": "data_fit"},
+    },
+}
+
+# Submit pipeline
+pipeline = client.pipeline.create(pipeline_config)
+print(f"Pipeline submitted: {pipeline.id}")
+
+# Poll for completion
+while True:
+    pipeline = client.pipeline.get(pipeline.id)
+    print(f"Status: {pipeline.status}")
+    if pipeline.status == "completed":
+        result = client.pipeline.result(pipeline.id)
+        print("Fitted parameters:", result.element_results["fit data"])
+        break
+    elif pipeline.status == "failed":
+        print("Pipeline failed:", pipeline.error)
+        break
+    time.sleep(2)
+```
+
+### Running simulations
+
+The client supports running battery simulations using the Universal Cycler Protocol (UCP) format:
+
+```python
+from ionworks import Ionworks
+
+client = Ionworks()
+
+# Define a charge/discharge protocol in YAML format
+protocol_yaml = """global:
+  initial_state_type: soc_percentage
+  initial_state_value: 50
+  initial_temperature: 25.0
+steps:
+  - Charge:
+      mode: C-rate
+      value: "0.6"
+      ends:
+        - Voltage > 4.2
+  - Rest:
+      duration: 3600
+  - Discharge:
+      mode: C-rate
+      value: "0.5"
+      ends:
+        - Voltage < 2.5
+"""
+
+# Create simulation with quick model
+config = {
+    "parameterized_model": {
+        "quick_model": {"capacity": 1.0, "chemistry": "NMC/Graphite"}
+    },
+    "protocol_experiment": {
+        "protocol": protocol_yaml,
+        "name": "NMC Charge Discharge Protocol",
+    },
+}
+
+result = client.simulation.protocol(config)
+print(f"Simulation ID: {result.simulation_id}")
+
+# Wait for completion
+simulation = client.simulation.wait_for_completion(
+    result.simulation_id, timeout=60, poll_interval=2
+)
+
+# Get results
+simulation_data = client.simulation.get_result(result.simulation_id)
+time_series = simulation_data.get("time_series", {})
+```
+
+## Error Handling
+
+The client will raise exceptions in the following cases:
+
+- Missing API credentials
+- Invalid API credentials
+- API request errors (will raise `IonworksError` with details)
+
+Make sure to handle these exceptions appropriately in your code.

ionworks_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+ionworks/__init__.py,sha256=OCNLH4VyRyH8SVjrNf-XmeltpvDBcAqwSWVJ2y2YMcY,85
+ionworks/cell_instance.py,sha256=BGssFTos_U4EBVmbTRr-WjXmL5ZGu57c0FweEzM_QB4,7649
+ionworks/cell_measurement.py,sha256=DfcgQMMs6K9Rc0SFjXgC3jWo-nQ-Wff_Bk_1Qys2lAo,11918
+ionworks/cell_specification.py,sha256=mr_H3ppFWoEB4bwQb6SaX-OgZdACw2JEJvrfIKV_d8o,3944
+ionworks/client.py,sha256=PPX2TGrKC64phNKglZJvJPFJl8oEB5qrmsre8h27ltI,4842
+ionworks/errors.py,sha256=9aTLnXgusWnRaegkWMsfXj4EDnqQ8vbvv0C_QAzSWKU,972
+ionworks/job.py,sha256=0ZokfwjhX4kseM3dl3CPKB5jr6-MzYuNJU4DUn7bck8,3505
+ionworks/models.py,sha256=DIm69Q_9GuR-XVMvhyvqhrZQuWVB6puHb_Tr1R7a7D8,4581
+ionworks/pipeline.py,sha256=_nDHQRIrc_g-k_OnrkFnIyOVNlwlMZgrppB-9tiLPO0,8403
+ionworks/simulation.py,sha256=ZHbIAz4UVTloUismjNSzAqzzKOaF_QijZtAKuWc0lIg,13860
+ionworks/validators.py,sha256=84hIefvXYvndkezEgnnxxmFeyLvCSr3d0wcbX9wRAWM,5728
+ionworks_api-0.1.0.dist-info/METADATA,sha256=hNFyvwrWXLf9nnYdbgeoRy1k6lPR75sEathLS7NNqCU,9235
+ionworks_api-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ionworks_api-0.1.0.dist-info/RECORD,,

ionworks_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any