morphopt 3.2.0__tar.gz → 3.2.2__tar.gz

{morphopt-3.2.0 → morphopt-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphopt
-Version: 3.2.0
+Version: 3.2.2
 Summary: A morphing optimization framework using PyTorch and Abaqus.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -16,7 +16,7 @@ Requires-Dist: gmsh>=4.15.0
 Requires-Dist: tabulate>=0.9.0
 Requires-Dist: imageio>=2.37.3
 Requires-Dist: bspmap>=1.0.3
-Requires-Dist: torchfea>=1.1.0
+Requires-Dist: torchfea>=1.1.1
 Requires-Dist: trimesh>=4.11.5
 Requires-Dist: networkx>=3.6.1
 Requires-Dist: scipy>=1.17.1

{morphopt-3.2.0 → morphopt-3.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "morphopt"
-version = "3.2.0"
+version = "3.2.2"
 description = "A morphing optimization framework using PyTorch and Abaqus."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -17,7 +17,7 @@ dependencies = [
     "tabulate>=0.9.0",
     "imageio>=2.37.3",
     "bspmap>=1.0.3",
-    "torchfea>=1.1.0",
+    "torchfea>=1.1.1",
     "trimesh>=4.11.5",
     "networkx>=3.6.1",
     "scipy>=1.17.1",

{morphopt-3.2.0 → morphopt-3.2.2}/src/morphopt/__init__.py

@@ -2,6 +2,13 @@
 A differentiable structural optimization framework that eliminates manual sensitivity derivation by fusing the adjoint method with automatic differentiation (AD). The sensitivity corresponds to the virtual work of residual force derivatives on the adjoint displacement field, computed via a single backpropagation through the residual graph. MorphOpt provides a unified interface for geometry, load, and material definition, calls torchfea for GPU-accelerated differentiable nonlinear FEA and adjoint-AD sensitivity, and employs a trust-region optimizer with L-BFGS for design updates. Validated on SIMP topology optimization with B-spline density fields and pneumatic soft robot shape optimization with deformation-dependent follower loads.
 """
 
+# Torch and TorchFEA use GNU OpenMP in this environment.  Set MKL's matching
+# threading layer before importing any module that can load NumPy or Torch.
+import os as __os
+import sys as __sys
+
+if __sys.platform.startswith("linux"):
+    __os.environ["MKL_THREADING_LAYER"] = "GNU"
 
 # region: Logging Configuration
 import logging as __logging
@@ -57,7 +64,10 @@ def enable_logging(level=__logging.INFO, log_file=None, file_log_level=__logging
 
 # region optcore imports
 from .optcore.controller import Controller
-from .optcore.modelparams import FEAParams, FixedGeometryINP, FixedGeometry, HomogeneousMaterial, Params
+from .optcore.modelparams import (
+    FEAParams, FixedGeometryINP, FixedGeometryTorchFEA, FixedGeometry,
+    MaterialsParams, Params,
+)
 from .optcore.solver import Solver
 from .optcore.modelparams import Params
 from .optcore.updaters import Updaters
@@ -79,4 +89,3 @@ from .utils import check_gradients, get_controller
 # endregion
 
 controller: Controller = None
-

{morphopt-3.2.0 → morphopt-3.2.2}/src/morphopt/codesign/__init__.py

@@ -1,13 +1,15 @@
-from .material import CodesignMaterials
 from .geometry import CodesignGeometry
 from .constraints import InwardCurvatureRadius, OffsetSurfaceMinThickness
 from .feaparams import CodesignFEAParams
 from .params import Params
-from ..optcore import Solver, Updaters
+from ..optcore import (
+    MaterialsParams, Solver, Updaters,
+)
 from ..shapeopt import GeometryParams, UpdaterGeometries, ObjectiveFunction
 from ..simp import UpdaterMaterials
+from ..simp import SIMP_BSPFieldMaterials
 
-def plot_geometry_and_materials(geometry: CodesignGeometry, materials: CodesignMaterials):
+def plot_geometry_and_materials(geometry: CodesignGeometry, materials: MaterialsParams):
     import pyvista as pv
     plotter = pv.Plotter(window_size=(1400, 900))
     plotter.set_background('white')
@@ -15,4 +17,4 @@ def plot_geometry_and_materials(geometry: CodesignGeometry, materials: CodesignM
     plotter = materials.plot(plotter=plotter)
     geometry.plot(plotter=plotter, opacity=[0.0, 1.0])
 
-    plotter.show()
+    plotter.show()

{morphopt-3.2.0 → morphopt-3.2.2}/src/morphopt/codesign/constraints.py

@@ -49,17 +49,28 @@ class InwardCurvatureRadius(BaseConstraints):
         super().__init__()
 
         self.geometry = geometry
+        """Stores the geometry used by InwardCurvatureRadius."""
         self.surface_start = int(surface_start)
+        """Stores the surface start used by InwardCurvatureRadius."""
         self.surface_ids = None if surface_ids is None else [int(i) for i in surface_ids]
+        """Stores the surface ids used by InwardCurvatureRadius."""
 
         self.margin = margin
+        """Stores the margin used by InwardCurvatureRadius."""
         self.margin_ratio = float(margin_ratio)
+        """Stores the margin ratio used by InwardCurvatureRadius."""
         self.barrier_thre_ratio = float(barrier_thre_ratio)
+        """Stores the barrier thre ratio used by InwardCurvatureRadius."""
         self.barrier_ratio = float(barrier_ratio)
+        """Stores the barrier ratio used by InwardCurvatureRadius."""
         self.p = int(p)
+        """Stores the p used by InwardCurvatureRadius."""
         self.penalty_scale = float(penalty_scale)
+        """Stores the penalty scale used by InwardCurvatureRadius."""
         self.hard_violation_beta = float(hard_violation_beta)
+        """Stores the hard violation beta used by InwardCurvatureRadius."""
         self.normal_sign = 1.0 if normal_sign >= 0 else -1.0
+        """Stores the normal sign used by InwardCurvatureRadius."""
 
     @staticmethod
     def _principal_curvatures(rdu: torch.Tensor, rdu2: torch.Tensor, eps: float = 1e-12) -> tuple[torch.Tensor, torch.Tensor]:
@@ -119,7 +130,6 @@ class InwardCurvatureRadius(BaseConstraints):
 
         return loss
 
-
 class OffsetSurfaceMinThickness(BaseConstraints):
     """
     Enforce a minimum distance on the offset surface to reduce self-intersection risk.
@@ -148,23 +158,39 @@ class OffsetSurfaceMinThickness(BaseConstraints):
         super().__init__()
 
         self.geometry = geometry
+        """Stores the geometry used by OffsetSurfaceMinThickness."""
         self.surface_start = int(surface_start)
+        """Stores the surface start used by OffsetSurfaceMinThickness."""
         self.surface_ids = None if surface_ids is None else [int(i) for i in surface_ids]
+        """Stores the surface ids used by OffsetSurfaceMinThickness."""
 
         self.min_distance = min_distance
+        """Stores the min distance used by OffsetSurfaceMinThickness."""
         self.search_ratio = float(search_ratio)
+        """Stores the search ratio used by OffsetSurfaceMinThickness."""
         self.barrier_thre_ratio = float(barrier_thre_ratio)
+        """Stores the barrier thre ratio used by OffsetSurfaceMinThickness."""
         self.barrier_ratio = float(barrier_ratio)
+        """Stores the barrier ratio used by OffsetSurfaceMinThickness."""
         self.p = int(p)
+        """Stores the p used by OffsetSurfaceMinThickness."""
         self.penalty_scale = float(penalty_scale)
+        """Stores the penalty scale used by OffsetSurfaceMinThickness."""
         self.hard_violation_beta = float(hard_violation_beta)
+        """Stores the hard violation beta used by OffsetSurfaceMinThickness."""
         self.normal_sign = 1.0 if normal_sign >= 0 else -1.0
+        """Stores the normal sign used by OffsetSurfaceMinThickness."""
         self.normal_opposition_thre = float(normal_opposition_thre)
+        """Stores the normal opposition thre used by OffsetSurfaceMinThickness."""
         self.normal_min = float(normal_min)
+        """Stores the normal min used by OffsetSurfaceMinThickness."""
         self.normal_max = float(normal_max)
+        """Stores the normal max used by OffsetSurfaceMinThickness."""
 
         self._neighbor_pairs: dict[int, torch.Tensor] = {}
+        """Stores the neighbor pairs used by OffsetSurfaceMinThickness."""
         self._neighbor_mindist: dict[int, torch.Tensor] = {}
+        """Stores the neighbor mindist used by OffsetSurfaceMinThickness."""
 
     def _selected_surface_ids(self, n_surface: int) -> list[int]:
         if self.surface_ids is None:
@@ -265,4 +291,3 @@ class OffsetSurfaceMinThickness(BaseConstraints):
                 loss = loss + (penalty_strong * scaler_n0[indexl] * scaler_n1[indexl]).sum()
 
         return loss
-

{morphopt-3.2.0 → morphopt-3.2.2}/src/morphopt/codesign/feaparams.py

@@ -4,6 +4,7 @@ import torch
 import numpy as np
 
 import torchfea
+import morphopt
 from .. import FEAParams
 import bspmap
 
@@ -15,7 +16,11 @@ class CodesignFEAParams(FEAParams):
 
     def create_fea(self, assembly: torchfea.Assembly) -> torchfea.FEAController:
         fe = super().create_fea(assembly=assembly)
-        fe_part = fe.assembly.get_part('final_model')
+        geometry = getattr(getattr(morphopt, "controller", None), "params", None)
+        geometry = getattr(geometry, "geometry", None)
+        part_name = getattr(geometry, "part_name", "final_model")
+        instance_name = getattr(geometry, "instance_name", "final_model")
+        fe_part = fe.assembly.get_part(part_name)
 
         if 'C3D6' in fe_part.elems:
             element_shell = fe_part.elems['C3D6']
@@ -40,10 +45,10 @@ class CodesignFEAParams(FEAParams):
             )
             surfcenter = surfnodes.mean(dim=1)
 
-            fe.assembly.get_instance('final_model').exterior_surface = 'surface_1_offset'
+            fe.assembly.get_instance(instance_name).exterior_surface = 'surface_1_offset'
 
-            mesh_1all = fe.assembly.get_instance('final_model').get_mesh(surf_name='surface_1_All')
-            mesh_1offset = fe.assembly.get_instance('final_model').get_mesh(surf_name='surface_1_offset')
+            mesh_1all = fe.assembly.get_instance(instance_name).get_mesh(surf_name='surface_1_All')
+            mesh_1offset = fe.assembly.get_instance(instance_name).get_mesh(surf_name='surface_1_offset')
 
             import morphopt
             normal_cpgeo = morphopt.controller.params.geometry.surface_list[1].get_normals(torch.from_numpy(morphopt.controller.params.geometry.surface_list[1].surf_node_uv).to(torch.get_default_device()))

{morphopt-3.2.0 → morphopt-3.2.2}/src/morphopt/codesign/geometry.py

@@ -6,10 +6,6 @@ import torchfea
 
 class CodesignGeometry(GeometryParams):
 
-
-    
-
-
     def __init__(self, 
                  fea_seed_size: float,
                  mesh_order: int = 1,
@@ -50,12 +46,19 @@ class CodesignGeometry(GeometryParams):
         """Element-id offset for the shell block (0-based)."""
 
         self._reinit_opt_steps: int = 100
+        """Stores the reinit opt steps used by CodesignGeometry."""
         self._reinit_opt_lr: float = 5e-3
+        """Stores the reinit opt lr used by CodesignGeometry."""
         self._reinit_opt_curvature_weight: float = 1e2
+        """Stores the reinit opt curvature weight used by CodesignGeometry."""
         self._reinit_opt_shape_weight: float = 1e2
+        """Stores the reinit opt shape weight used by CodesignGeometry."""
         self._reinit_opt_curvature_margin_ratio: float = 0.25
+        """Stores the reinit opt curvature margin ratio used by CodesignGeometry."""
         self._reinit_opt_inward_sign: float = 1.0
+        """Stores the reinit opt inward sign used by CodesignGeometry."""
         self._reinit_opt_accept_only_improve: bool = True
+        """Stores the reinit opt accept only improve used by CodesignGeometry."""
 
     # def reinitialize(self, iteration):
     #     super().reinitialize(iteration)
@@ -334,7 +337,7 @@ class CodesignGeometry(GeometryParams):
         if len(self._node_idx) == 0 or self._tri_local is None:
             return
         
-        part = assembly.get_part('final_model')
+        part = assembly.get_part(self.part_name)
 
         nodes = part.nodes.clone()
         base_ids_t = torch.as_tensor(self._node_idx[0], dtype=torch.long, device=nodes.device)
@@ -356,4 +359,4 @@ class CodesignGeometry(GeometryParams):
 
     def plot(self, plotter=None, opacity = None, meshes=None):
         opacity = [0.0 if i == 0 else 1.0 for i in range(self.num_surface)]
-        return super().plot(plotter, opacity, meshes)
+        return super().plot(plotter, opacity, meshes)

morphopt-3.2.2/src/morphopt/optcore/__init__.py

@@ -0,0 +1,8 @@
+from .modelparams import (
+    Params, BaseGeometry, FEAParams,
+    MaterialsParams, BaseParams,
+    FixedGeometryINP, FixedGeometryTorchFEA, FixedGeometry,
+)
+from .updaters import BaseUpdater, Updaters
+from .solver import Solver
+from .objfunc import ObjectiveFunction

{morphopt-3.2.0 → morphopt-3.2.2}/src/morphopt/optcore/controller.py

@@ -323,8 +323,22 @@ class Controller:
         self.history.append('objective', loss.item())
         self.history.append('metrics', self.objfun.get_metrics())
         self.history.append('time', [t1-t0, t2-t1, t3-t2, t4-t3])
-        self.history.append('num_elements', sum([elem._elems.shape[0] for elem in self.objfun.fe.assembly.get_instance('final_model').elems.values()]))
-        self.history.append('num_nodes', self.objfun.fe.assembly.get_instance('final_model').nodes.shape[0])
+        # Shape/codesign jobs historically used one ``final_model`` instance,
+        # while a SIMP job may import an Assembly from torchfea-ui with
+        # arbitrary Part/Instance names (for example ``Part-1-1``).  Record
+        # statistics from the actual Assembly instead of assuming a name.
+        instances = self.objfun.fe.assembly._instances.values()
+        num_elements = sum(
+            element._elems.shape[0]
+            for instance in instances
+            for element in instance.elems.values()
+        )
+        num_nodes = sum(
+            instance.nodes.shape[0]
+            for instance in self.objfun.fe.assembly._instances.values()
+        )
+        self.history.append('num_elements', num_elements)
+        self.history.append('num_nodes', num_nodes)
 
     def print_info(self, t0, t1, t2, t3, t4) -> None:
         """

morphopt-3.2.2/src/morphopt/optcore/modelparams/__init__.py

@@ -0,0 +1,5 @@
+from .geometry import FixedGeometryINP, FixedGeometryTorchFEA, FixedGeometry, BaseGeometry
+from .feaparams import FEAParams
+from .materials import MaterialsParams
+from .params import Params
+from .baseparam import BaseParams

morphopt-3.2.2/src/morphopt/optcore/modelparams/geometry.py

@@ -0,0 +1,251 @@
+"""Geometry parameter classes and the TorchFEA Assembly import helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+import torchfea
+
+from .baseparam import BaseParams
+
+
+# ---------------------------------------------------------------------------
+# TorchFEA model import helpers
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class PartSummary:
+    name: str
+    node_sets: tuple[str, ...]
+    element_sets: tuple[str, ...]
+    surface_sets: tuple[str, ...]
+    element_types: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class InstanceSummary:
+    name: str
+    part_name: str
+
+
+@dataclass(frozen=True)
+class TorchFEAModelSummary:
+    path: str
+    parts: tuple[PartSummary, ...]
+    instances: tuple[InstanceSummary, ...]
+
+    def part_for_instance(self, instance_name: str) -> PartSummary | None:
+        instance = next(
+            (item for item in self.instances if item.name == instance_name), None)
+        if instance is None:
+            return None
+        return next(
+            (item for item in self.parts if item.name == instance.part_name), None)
+
+
+def resolve_model_path(model_directory: str, model_filename: str = "") -> Path:
+    """Resolve one exported TorchFEA ``.npz`` inside ``model_directory``."""
+    directory = Path(model_directory).expanduser().resolve()
+    if not directory.is_dir():
+        raise FileNotFoundError(
+            f"TorchFEA model directory does not exist: {directory}")
+
+    if model_filename:
+        candidate = Path(model_filename)
+        path = candidate if candidate.is_absolute() else directory / candidate
+        path = path.expanduser().resolve()
+        if not path.is_file():
+            raise FileNotFoundError(f"TorchFEA model file does not exist: {path}")
+        return path
+
+    candidates = sorted(
+        directory.glob("*.npz"), key=lambda item: item.stat().st_mtime_ns,
+        reverse=True)
+    if not candidates:
+        raise FileNotFoundError(
+            f"No TorchFEA .npz model was found in: {directory}")
+    return candidates[0].resolve()
+
+
+def inspect_model(model_directory: str,
+                  model_filename: str = "") -> TorchFEAModelSummary:
+    """Return selectable Part/Instance/set names from an exported model."""
+    path = resolve_model_path(model_directory, model_filename)
+    return _inspect_model_cached(str(path), path.stat().st_mtime_ns)
+
+
+@lru_cache(maxsize=16)
+def _inspect_model_cached(path: str, _mtime_ns: int) -> TorchFEAModelSummary:
+    controller = _read_controller(path)
+    source = controller.assembly
+    if source is None:
+        raise ValueError("The TorchFEA model does not contain an Assembly.")
+
+    parts = tuple(
+        PartSummary(
+            name=name,
+            node_sets=tuple(part.set_nodes.keys()),
+            element_sets=tuple(part.set_elements.keys()),
+            surface_sets=tuple(part.surfaces.keys()),
+            element_types=tuple(part.elems.keys()),
+        )
+        for name, part in source._parts.items()
+    )
+    instances = tuple(
+        InstanceSummary(name=name, part_name=instance.part_name)
+        for name, instance in source._instances.items()
+    )
+    if not parts:
+        raise ValueError("The TorchFEA Assembly contains no Parts.")
+    if not instances:
+        raise ValueError("The TorchFEA Assembly contains no Instances.")
+    return TorchFEAModelSummary(str(Path(path).resolve()), parts, instances)
+
+
+def load_geometry_assembly(model_directory: str,
+                           model_filename: str = "") -> torchfea.Assembly:
+    """Load a clean Assembly containing only cloned Parts and Instances."""
+    path = resolve_model_path(model_directory, model_filename)
+    controller = _read_controller(str(path))
+    source = controller.assembly
+    if source is None:
+        raise ValueError("The TorchFEA model does not contain an Assembly.")
+
+    assembly = torchfea.Assembly()
+    for name, part in source._parts.items():
+        cloned_part = torchfea.Serializable._deserialize(part._serialize())
+        if (cloned_part.exterior_surface == "extern"
+                and "extern" not in cloned_part.surfaces):
+            boundary = []
+            for element in cloned_part.elems.values():
+                boundary.extend(element.extract_boundary_surface_set())
+            if boundary:
+                cloned_part.surfaces["extern"] = boundary
+        assembly.add_part(cloned_part, name=name)
+    for name, instance in source._instances.items():
+        cloned_instance = torchfea.Serializable._deserialize(instance._serialize())
+        assembly.add_instance(cloned_instance, name=name)
+
+    if not assembly._parts:
+        raise ValueError("The TorchFEA Assembly contains no Parts.")
+    if not assembly._instances:
+        raise ValueError("The TorchFEA Assembly contains no Instances.")
+    return assembly
+
+
+def _read_controller(path: str) -> torchfea.FEAController:
+    """Deserialize a controller without initializing its analysis objects."""
+    with np.load(path, allow_pickle=True) as loaded:
+        if "data" not in loaded:
+            raise ValueError("The .npz file is not a TorchFEA model archive.")
+        return torchfea.FEAController._deserialize(loaded["data"])
+
+class BaseGeometry(BaseParams):
+    """
+    Base class for geometry parameter classes.
+
+    Subclasses must provide the mesh/geometry generation and assembly modification
+    behavior used by the optimization pipeline.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(**kwargs)
+
+    def generate(self, path_result: str, pools=None) -> torchfea.Assembly:
+        """Generate the FEA part for the current geometry."""
+        raise NotImplementedError
+    
+
+
+class FixedGeometry(BaseGeometry):
+    """
+    Base class for geometry whose FE assembly stays fixed during optimization.
+
+    Subclasses may read an INP mesh or a saved TorchFEA model.  In both cases
+    the assembly is built once and reused across optimization iterations.
+    """
+    def __init__(self):
+        super().__init__()
+        self._assembly: torchfea.Assembly = None
+        """
+        The FEA assembly containing the geometry for the optimization problem. This assembly is generated from a fixed mesh and does not change during optimization iterations.
+        """
+
+    @property
+    def assembly(self) -> torchfea.Assembly:
+        """
+        Get the FEA assembly containing the geometry for the optimization problem.
+
+        Returns:
+            torchfea.Assembly: The FEA assembly containing the geometry.
+        """
+        if self._assembly is None:
+            self._assembly = self.define_assembly()
+        return self._assembly
+
+    def define_assembly(self)-> torchfea.Assembly:
+        """
+        Define the assembly for the geometry using node and element data.
+
+        This method should be implemented in subclasses to create the assembly based on specific node and element data.
+
+        Returns:
+            torchfea.Assembly: The defined assembly for the geometry.
+        """
+        raise NotImplementedError
+
+    def generate(self, *args, **kwargs):
+        """Return the lazily built fixed torchfea assembly."""
+        return self.assembly
+
+class FixedGeometryINP(FixedGeometry):
+    """
+    Geometry parameters class for fixed mesh geometry using an Abaqus .inp file.
+    """
+    def __init__(self, mesh_file: str, part_name: str = 'final_model'):
+        super().__init__()
+        self._mesh_file = mesh_file
+        """
+        The file path of the mesh to be loaded for the geometry.
+        """
+
+        self._part_name = part_name
+        """The name of the part in the Abaqus INP file to be used for the geometry."""
+
+    def define_assembly(self):
+        inp = torchfea.FEA_INP()
+        inp.read_inp(self._mesh_file)
+
+        fe_ext = torchfea.from_inp(inp)
+        
+        assembly = torchfea.Assembly()
+
+        assembly.add_part(part=fe_ext.assembly.get_part(self._part_name), name='final_model')
+        instance = torchfea.Instance(part_name='final_model')
+        assembly.add_instance(instance=instance, name='final_model')
+        instance.exterior_surface = 'surface_0_All'
+        return assembly
+
+
+class FixedGeometryTorchFEA(FixedGeometry):
+    """Fixed geometry imported from a model exported by ``torchfea-ui``.
+
+    Only the saved Parts and Instances are used.  MorphOpt creates its own
+    loads, constraints, boundary conditions, reference points, and solver.
+    """
+
+    def __init__(self, model_directory: str, model_filename: str):
+        super().__init__()
+        self.model_directory = str(model_directory)
+        self.model_filename = str(model_filename)
+        # Fail early with a path-specific message while keeping assembly
+        # construction lazy.
+        self.model_path = str(resolve_model_path(
+            self.model_directory, self.model_filename))
+
+    def define_assembly(self) -> torchfea.Assembly:
+        return load_geometry_assembly(
+            self.model_directory, self.model_filename)

morphopt-3.2.2/src/morphopt/optcore/modelparams/materialinterface/__init__.py

@@ -0,0 +1,11 @@
+"""Material assignment interfaces."""
+
+from .basematerialinterface import BaseMaterialInterface
+from .homogeneousmaterial import HomogeneousMaterial
+from .materialmodels import MaterialModels
+
+__all__ = [
+    "BaseMaterialInterface",
+    "HomogeneousMaterial",
+    "MaterialModels",
+]

morphopt-3.2.2/src/morphopt/optcore/modelparams/materialinterface/basematerialinterface.py

@@ -0,0 +1,69 @@
+"""Base class for material assignments to TorchFEA parts."""
+
+from __future__ import annotations
+
+import torch
+import torchfea
+
+from ..baseparam import BaseParams
+from .materialmodels import MaterialModels
+
+
+class BaseMaterialInterface(BaseParams):
+    """Assign one material definition to elements in one Part.
+
+    ``elementname`` may be empty. In that case the interface is applied to
+    every element family in ``part_name``.
+    """
+
+    from .materialmodels import MaterialModels as materialmodels
+
+    def __init__(
+            self,
+            part_name: str,
+            material_parameters: MaterialModels.MaterialParameters,
+            elementname: str = "",
+            density: float = 0.0,
+    ) -> None:
+        super().__init__()
+        self.part_name = str(part_name or "").strip()
+        if not self.part_name:
+            raise ValueError("part_name cannot be empty.")
+        self.elementname = str(elementname or "").strip()
+        self.material_parameters: MaterialModels.MaterialParameters = material_parameters
+        self._density: float = float(density)
+        self._name: str = ""
+
+    @property
+    def density(self) -> float:
+        """Return the mass density assigned to the target elements."""
+        return self._density
+
+    @density.setter
+    def density(self, value: float) -> None:
+        """Set the mass density assigned to the target elements."""
+        self._density = float(value)
+
+    def target_elements(
+            self,
+            assembly: torchfea.Assembly,
+    ) -> list[tuple[str, torchfea.elements.Element_3D]]:
+        """Return the selected element families from the target Part."""
+        part = assembly.get_part(self.part_name)
+        if self.elementname:
+            if self.elementname not in part.elems:
+                raise KeyError(
+                    f"Element {self.elementname!r} does not exist on Part "
+                    f"{self.part_name!r}.")
+            return [(self.elementname, part.elems[self.elementname])]
+        if not part.elems:
+            raise ValueError(f"Part {self.part_name!r} contains no elements.")
+        return list(part.elems.items())
+
+    def set_materials(self, fe: torchfea.FEAController) -> None:
+        """Assign this interface to its target elements."""
+        raise NotImplementedError
+
+    def get_design_values(self) -> torch.Tensor:
+        """Return live design values for a designable material interface."""
+        return torch.zeros(0)