feat: use pydantic for materials (#1233)

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: mhoeijm

doc/source/changelog/1233.added.md

@@ -0,0 +1 @@
+Use pydantic for materials

examples/preprocessor/demo-material_pr.py

@@ -35,19 +35,20 @@
 
 import matplotlib.pyplot as plt
 
-from ansys.health.heart.settings.material.curve import (
-    ActiveCurve,
-    constant_ca2,
-    kumaraswamy_active,
-)
-from ansys.health.heart.settings.material.ep_material import CellModel, EPMaterial
-from ansys.health.heart.settings.material.material import (
+from ansys.health.heart.settings.material.cell_models import Tentusscher
+from ansys.health.heart.settings.material.curve import kumaraswamy_active
+from ansys.health.heart.settings.material.ep_material import EPMaterial
+from ansys.health.heart.settings.material.material_pyd import (
     ACTIVE,
     ANISO,
     ISO,
-    ActiveModel,
+    ActiveCurve,
+    ActiveModel1,
+    ActiveModel3,
+    HGOFiber,
     Mat295,
     NeoHookean,
+    constant_ca2,
 )
 
 ###############################################################################
@@ -74,18 +75,18 @@
 iso = ISO(k1=1, k2=1, kappa=100)
 
 # step 2: create an anisotropic module
-fiber = ANISO.HGOFiber(k1=1, k2=1)
+fiber = HGOFiber(k1=1, k2=1)
 aniso1 = ANISO(fibers=[fiber])
 
 # Create fiber with sheet, and their interactions
-sheet = ANISO.HGOFiber(k1=1, k2=1)
+sheet = HGOFiber(k1=1, k2=1)
 aniso2 = ANISO(fibers=[fiber, sheet], k1fs=1, k2fs=1)
 
 # step3: create the active module
 
 # example 1:
 # create active model 1
-ac_model1 = ActiveModel.Model1()
+ac_model1 = ActiveModel1()
 # create Ca2+ curve
 ac_curve1 = ActiveCurve(constant_ca2(tb=800, ca2ionm=ac_model1.ca2ionm), type="ca2", threshold=0.5)
 # build active module
@@ -103,7 +104,7 @@
 
 # example 2
 # create active model 3
-ac_model3 = ActiveModel.Model3()
+ac_model3 = ActiveModel3()
 # create a stress curve and show
 ac_curve3 = ActiveCurve(kumaraswamy_active(t_end=800), type="stress")
 fig = ac_curve3.plot_time_vs_stress()
@@ -133,7 +134,7 @@
 # Create EP materials
 # ~~~~~~~~~~~~~~~~~~~
 ep_mat_active = EPMaterial.Active(
-    sigma_fiber=1, sigma_sheet=0.5, beta=140, cm=0.01, cell_model=CellModel.Tentusscher()
+    sigma_fiber=1, sigma_sheet=0.5, beta=140, cm=0.01, cell_model=Tentusscher()
 )
 epinsulator = EPMaterial.Insulator()
 

pyproject.toml

@@ -40,6 +40,7 @@ dependencies = [
     "scipy<=1.15.3",
     "validators>=0.34.0",
     "vtk>=9.1.0,<9.6,!=9.4.*",
+    "pydantic>=2.0.0"
 ]
 
 # Optional dependencies:

src/ansys/health/heart/settings/material/cell_models.py

@@ -0,0 +1,179 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Module to collect ionic cell models."""
+
+from pydantic import BaseModel
+
+
+class Tentusscher(BaseModel):
+    """Data for Tentusscher cell model."""
+
+    gas_constant: float = 8314.472
+    t: float = 310
+    faraday_constant: float = 96485.3415
+    cm: float = 0.185
+    vc: float = 0.016404
+    vsr: float = 0.001094
+    vss: float = 0.00005468
+    pkna: float = 0.03
+    ko: float = 5.4
+    nao: float = 140.0
+    cao: float = 2.0
+    gk1: float = 5.405
+    gkr: float = 0.153
+    gna: float = 14.838
+    gbna: float = 0.0002
+    gcal: float = 0.0000398
+    gbca: float = 0.000592
+    gpca: float = 0.1238
+    gpk: float = 0.0146
+    pnak: float = 2.724
+    km: float = 1.0
+    kmna: float = 40.0
+    knaca: float = 1000.0
+    ksat: float = 0.1
+    alpha: float = 2.5
+    gamma: float = 0.35
+    kmca: float = 1.38
+    kmnai: float = 87.5
+    kpca: float = 0.0005
+    k1: float = 0.15
+    k2: float = 0.045
+    k3: float = 0.06
+    k4: float = 0.005
+    ec: float = 1.5
+    maxsr: float = 2.5
+    minsr: float = 1.0
+    vrel: float = 0.102
+    vleak: float = 0.00036
+    vxfer: float = 0.0038
+    vmaxup: float = 0.006375
+    kup: float = 0.00025
+    bufc: float = 0.2
+    kbufc: float = 0.001
+    bufsr: float = 10.0
+    kbufsf: float = 0.3
+    bufss: float = 0.4
+    kbufss: float = 0.00025
+    # gas_constant=8314.472,
+    # faraday_constant=96485.3415,
+    gks: float = 0.392
+    gto: float = 0.294
+    v: float = -85.23
+    ki: float = 136.89
+    nai: float = 8.604
+    cai: float = 0.000126
+    cass: float = 0.00036
+    casr: float = 3.64
+    rpri: float = 0.9073
+    xr1: float = 0.00621
+    xr2: float = 0.4712
+    xs: float = 0.0095
+    m: float = 0.00172
+    h: float = 0.7444
+    j: float = 0.7045
+    d: float = 3.373e-5
+    f: float = 0.7888
+    f2: float = 0.9755
+    fcass: float = 0.9953
+    s: float = 0.999998
+    r: float = 2.42e-8
+    pass
+
+
+class TentusscherEndo(Tentusscher):
+    """Data for Tentusscher cell model in its endocardium version."""
+
+    gks: float = 0.392
+    gto: float = 0.073
+    v: float = -86.709
+    ki: float = 138.4
+    nai: float = 10.355
+    cai: float = 0.00013
+    cass: float = 0.00036
+    casr: float = 3.715
+    rpri: float = 0.9068
+    xr1: float = 0.00448
+    xr2: float = 0.476
+    xs: float = 0.0087
+    m: float = 0.00155
+    h: float = 0.7573
+    j: float = 0.7225
+    d: float = 3.164e-5
+    f: float = 0.8009
+    f2: float = 0.9778
+    fcass: float = 0.9953
+    s: float = 0.3212
+    r: float = 2.235e-8
+
+
+class TentusscherEpi(Tentusscher):
+    """Data for Tentusscher cell model in its epicardium version."""
+
+    gks: float = 0.392
+    gto: float = 0.294
+    v: float = -85.23
+    ki: float = 136.89
+    nai: float = 8.604
+    cai: float = 0.000126
+    cass: float = 0.00036
+    casr: float = 3.64
+    rpri: float = 0.9073
+    xr1: float = 0.00621
+    xr2: float = 0.4712
+    xs: float = 0.0095
+    m: float = 0.00172
+    h: float = 0.7444
+    j: float = 0.7045
+    d: float = 3.373e-5
+    f: float = 0.7888
+    f2: float = 0.9755
+    fcass: float = 0.9953
+    s: float = 0.999998
+    r: float = 2.42e-8
+
+
+class TentusscherMid(Tentusscher):
+    """Data for Tentusscher cell model in its mid-myocardium version."""
+
+    gks: float = 0.098
+    gto: float = 0.294
+    v: float = -85.423
+    ki: float = 138.52
+    nai: float = 10.132
+    cai: float = 0.000153
+    cass: float = 0.00042
+    casr: float = 4.272
+    rpri: float = 0.8978
+    xr1: float = 0.0165
+    xr2: float = 0.473
+    xs: float = 0.0174
+    m: float = 0.00165
+    h: float = 0.749
+    j: float = 0.6788
+    d: float = 3.288e-5
+    f: float = 0.7026
+    f2: float = 0.9526
+    fcass: float = 0.9942
+    s: float = 0.999998
+    r: float = 2.347e-8

src/ansys/health/heart/settings/material/curve.py

@@ -126,6 +126,7 @@ def constant_ca2(tb: float = 800, ca2ionm: float = 4.35) -> tuple[np.ndarray, np
     return (t, v)
 
 
+# TODO: Use pydantic to easily (de)serialize the curve.
 class ActiveCurve:
     """Active stress or Ca2+ curve."""
 

src/ansys/health/heart/settings/material/ep_material.py

@@ -25,9 +25,13 @@
 from dataclasses import dataclass, field
 from typing import Optional
 
+from deprecated import deprecated
+
 from ansys.health.heart.settings.defaults import electrophysiology as ep_defaults
+import ansys.health.heart.settings.material.cell_models as cell_models
 
 
+@deprecated("Use the cell models in src.ansys.health.heart.settings.material.cell_models instead.")
 @dataclass
 class CellModel:
     """Abstract class for different cell models."""
@@ -211,6 +215,10 @@ def __post_init__(self):
             self.sigma_sheet = self.sigma_sheet_normal
 
 
+@deprecated(
+    reason="""Use the Pydantic-based EPMaterial instead.
+    import ansys.health.heart.settings.material.ep_material_pyd as ep_material"""
+)
 @dataclass
 class EPMaterial(EPMaterialModel):
     """EP material module."""
@@ -247,13 +255,15 @@ class Active(EPMaterialModel):
         sigma_fiber: float = sig1
         sigma_sheet: Optional[float] = sig2
         sigma_sheet_normal: Optional[float] = sig3
-        cell_model: CellModel = field(default_factory=lambda: CellModel.Tentusscher())
+        cell_model: cell_models.Tentusscher = field(
+            default_factory=lambda: cell_models.Tentusscher()
+        )
 
     class ActiveBeam(Active):
         """Hold data for beam active EP material."""
 
         sigma_fiber = ep_defaults.material["beam"]["sigma"].m
-        cell_model = field(default_factory=lambda: CellModel.TentusscherEndo())
+        cell_model = field(default_factory=lambda: cell_models.TentusscherEndo())
         pmjres: float = ep_defaults.material["beam"]["pmjres"].m
 
     class Passive(EPMaterialModel):
@@ -272,16 +282,3 @@ class DummyMaterial:
         def __repr__(self):
             """Print a message."""
             return "Material is empty."
-
-
-if __name__ == "__main__":
-    m1 = EPMaterial.DummyMaterial()
-
-    tentus1 = CellModel.Tentusscher()
-    tentus2 = CellModel.TentusscherEndo()
-
-    mat1 = EPMaterial.Insulator()
-    mat2 = EPMaterial.Passive(sigma_fiber=0, sigma_sheet=2)
-    mat3 = EPMaterial.Active(sigma_fiber=1, sigma_sheet=2, sigma_sheet_normal=3)
-    mat4 = EPMaterial.Active(sigma_fiber=1, sigma_sheet=2, sigma_sheet_normal=3)
-    print("done")