metafold 0.12.dev1__tar.gz → 0.12.dev3__tar.gz

{metafold-0.12.dev1 → metafold-0.12.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metafold
-Version: 0.12.dev1
+Version: 0.12.dev3
 Summary: Metafold SDK for Python
 Author-email: Metafold 3D <info@metafold3d.com>
 License: Copyright 2024 Metafold 3D

{metafold-0.12.dev1 → metafold-0.12.dev3}/metafold/client.py

@@ -55,11 +55,16 @@ class Client:
             headers = {"Authorization": f"Bearer {self._auth.get_token()}"}
         r: Response = request(url, *args, **kwargs, headers=headers)
         if not r.ok:
-            body: dict[str, Any] = r.json()
-            # Error responses aren't entirely consistent in the Metafold API,
-            # for now we check for a handful of possible fields.
+            # Not all error responses are JSON so fall back to the status reason
+            try:
+                body: dict[str, Any] = r.json()
+            except ValueError:
+                body = {}
             reason = body.get("errors") or body.get("msg") or body.get("description")
-            raise HTTPError(f"HTTP error occurred: {reason or r.reason}")
+            raise HTTPError(
+                f"HTTP error occurred: {reason or r.reason} "
+                f"(status {r.status_code} for {r.request.method} {r.url})"
+            )
         return r
 
     def get(self, url: str, *args: Any, **kwargs: Any) ->  Response:

{metafold-0.12.dev1 → metafold-0.12.dev3}/metafold/simulation/__init__.py

@@ -1,4 +1,5 @@
 from metafold.simulation.compression_simulation import (
+    BoundaryCondition,
     CompressionSimulation,
     ExperimentBox,
     ExperimentCylinder,
@@ -14,6 +15,7 @@ from metafold.simulation.compression_simulation import (
     ExperimentSupportCylinder,
     ExperimentSupportMesh,
     ExperimentSupportParallelepiped,
+    ForceSource,
     ReferenceData,
     SimulationParameters,
     WorkflowStep,

{metafold-0.12.dev1 → metafold-0.12.dev3}/metafold/simulation/compression_simulation.py

@@ -21,6 +21,7 @@ from simulation_configurator import (
     Contact,
     Mpm,
 )
+from simulation_configurator.element import CompositeElement, Element
 from simulation_configurator.grid import Face
 from simulation_configurator.shapes import Box, File, Cylinder, Parallelepiped
 from plyfile import PlyData, PlyElement
@@ -71,6 +72,68 @@ ZERO_VELOCITY = [
 ]
 
 
+class BoundaryCondition(Enum):
+    SYMMETRIC          = "symmetric"           # symmetry plane (acts as frictionless wall)
+    VELOCITY_DIRICHLET = "velocity_dirichlet"  # velocity fixed to zero at the face
+    VELOCITY_NEUMANN   = "velocity_neumann"    # zero velocity gradient (free face)
+
+
+DEFAULT_BOUNDARY_CONDITIONS = {
+    "x-": BoundaryCondition.SYMMETRIC,
+    "x+": BoundaryCondition.SYMMETRIC,
+    "y-": BoundaryCondition.SYMMETRIC,
+    "y+": BoundaryCondition.SYMMETRIC,
+    "z-": BoundaryCondition.VELOCITY_DIRICHLET,
+    "z+": BoundaryCondition.VELOCITY_DIRICHLET,
+}
+
+
+def _velocity_neumann_face(side: str):
+    # simulation_configurator.Face only provides fixed (symmetry) and unfixed
+    # (velocity Dirichlet) faces; build the Neumann variant here until it can
+    # move into a simulation-configurator release.
+    face = CompositeElement("Face", {"side": side})
+    bc_type = CompositeElement(
+        "BCType",
+        {"id": "all", "label": "Velocity", "var": "Neumann"},
+    )
+    bc_type.add(Element("value", data="[0.0, 0.0, 0.0]"))
+    face.add(bc_type)
+    return face
+
+
+_FACE_BUILDERS = {
+    BoundaryCondition.SYMMETRIC: Face.fixed,
+    BoundaryCondition.VELOCITY_DIRICHLET: Face.unfixed,
+    BoundaryCondition.VELOCITY_NEUMANN: _velocity_neumann_face,
+}
+
+
+def _normalize_boundary_conditions(
+    boundary_conditions: dict,
+) -> dict[str, BoundaryCondition]:
+    """Merge per-face boundary conditions over the defaults.
+
+    Values may be BoundaryCondition members or their string values (as parsed
+    from an experiment manifest). Faces not present keep their default.
+    """
+    unknown = set(boundary_conditions) - set(DEFAULT_BOUNDARY_CONDITIONS)
+    if unknown:
+        raise ValueError(
+            f"Unknown boundary condition face(s) {sorted(unknown)}; "
+            f"expected faces {sorted(DEFAULT_BOUNDARY_CONDITIONS)}"
+        )
+    resolved = dict(DEFAULT_BOUNDARY_CONDITIONS)
+    for side, bc in boundary_conditions.items():
+        resolved[side] = BoundaryCondition(bc) if isinstance(bc, str) else bc
+    return resolved
+
+
+class ForceSource(Enum):
+    BOUNDARY_FORCE       = "boundary_force"        # uses boundary_force_zminus (default)
+    RIGID_REACTION_FORCE = "rigid_reaction_force"  # uses rigid reaction force of force_source_part
+
+
 @dataclass
 class SimulationParameters:
     init_time: float = 0.0
@@ -89,6 +152,15 @@ class SimulationParameters:
     extra_cells: list[int] = field(default_factory=lambda: [1, 1, 1])
     patches: list[int] = field(default_factory=lambda: [4, 2, 2])
 
+    # Per-face boundary conditions; faces omitted here use the default.
+    boundary_conditions: dict[str, BoundaryCondition] = field(
+        default_factory=lambda: dict(DEFAULT_BOUNDARY_CONDITIONS)
+    )
+    force_source: ForceSource = ForceSource.BOUNDARY_FORCE
+    # Part whose rigid_reaction_force feeds force-displacement when
+    # force_source is RIGID_REACTION_FORCE. Empty string means the piston.
+    force_source_part: str = ""
+
 
 @dataclass
 class ExperimentPart:
@@ -506,6 +578,21 @@ class CompressionSimulation:
                     p.restore_from_state_dict(saved)
                     break
 
+    @staticmethod
+    def cancel_active_workflows(client: MetafoldClient, project_id: str) -> list[str]:
+        """Cancel all in-flight (pending/started) workflows for a project.
+
+        Returns the number of workflows cancelled. Used when re-running an
+        experiment on an existing project, whose previous results we're about
+        to overwrite anyway.
+        """
+        cancelled = []
+        for state in ("pending", "started"):
+            for wf in client.workflows.list(q=f"state:{state}", project_id=project_id):
+                client.workflows.cancel(wf.id, project_id=project_id)
+                cancelled.append(wf.id)
+        return cancelled
+
     @staticmethod
     def find_or_create_project(
         project_name: str,
@@ -514,12 +601,17 @@ class CompressionSimulation:
         client_secret: Optional[str] = None,
         auth_domain: str = "metafold3d.us.auth0.com",
         base_url: str = "https://api.metafold3d.com/",
+        cancel_existing_workflows: bool = True,
     ) -> str:
         """Find an existing project by name or create a new one.
 
         Supply either access_token (server context — never reads from env) or
         client_id + client_secret (local/programmable use, reads from env via
         setup_client). base_url must match the audience the token was issued for.
+
+        When cancel_existing_workflows is True and an existing project is
+        reused, its running workflows are cancelled first.
+
         Returns the project_id string.
         """
         client = MetafoldClient(
@@ -534,7 +626,10 @@ class CompressionSimulation:
         except HTTPError:
             existing = []
         if existing:
-            return existing[0].id
+            project_id = existing[0].id
+            if cancel_existing_workflows:
+                CompressionSimulation.cancel_active_workflows(client, project_id)
+            return project_id
         created = client.projects.create(
             project_name,
             access=Access.PRIVATE,
@@ -775,17 +870,28 @@ class CompressionSimulation:
 
         grid_min = np.array(grid_patch["offset"], dtype=np.float32) * 1e-3
         grid_max = np.array(grid_patch["size"], dtype=np.float32) * 1e-3 + grid_min
-        grid_min[:2] -= self.simulation_parameters.margin_xy
-        grid_max[:2] += self.simulation_parameters.margin_xy
-        grid_max[2] += self.simulation_parameters.margin_z
 
-        # Expand grid to contain every rigid primitive's bounding box
+        # Expand grid to contain every part's bounding box, so nothing is
+        # clipped (e.g. a support/outsole extending below the representative
+        # part). Primitives report bounds via get_bounds() in metres, mesh
+        # parts via their sampled patch (offset/size in mm)
         for info in self.part_infos:
             part = info.part
             if isinstance(part, ExperimentPrimitive):
                 pmin, pmax = part.get_bounds()
-                grid_min = np.minimum(grid_min, pmin)
-                grid_max = np.maximum(grid_max, pmax)
+            elif info.patch:
+                pmin = np.array(info.patch["offset"], dtype=np.float32) / 1000.0
+                pmax = np.array(info.patch["size"], dtype=np.float32) / 1000.0 + pmin
+            else:
+                continue
+            grid_min = np.minimum(grid_min, pmin)
+            grid_max = np.maximum(grid_max, pmax)
+
+        # Apply margins after all parts included
+        grid_min[:2] -= self.simulation_parameters.margin_xy
+        grid_max[:2] += self.simulation_parameters.margin_xy
+        grid_min[2] -= self.simulation_parameters.margin_z
+        grid_max[2] += self.simulation_parameters.margin_z
 
         grid_size = grid_max - grid_min
         spacing = (
@@ -807,10 +913,11 @@ class CompressionSimulation:
             }
         )
         bcs = BoundaryConditions()
-        for side in ["x-", "x+", "y-", "y+"]:
-            bcs._sub_elements[side] = Face.fixed(side)
-        for side in ["z-", "z+"]:
-            bcs._sub_elements[side] = Face.unfixed(side)
+        boundary_conditions = _normalize_boundary_conditions(
+            self.simulation_parameters.boundary_conditions
+        )
+        for side, bc in boundary_conditions.items():
+            bcs._sub_elements[side] = _FACE_BUILDERS[bc](side)
         grid.add(bcs)
 
         store = GeometryStore()
@@ -867,16 +974,18 @@ class CompressionSimulation:
             store.add(geometry_element)
 
         outputs_indices_key = ",".join(str(i) for i in range(len(self.part_infos)))
+        all_outputs = [
+            "boundary_force_zminus",
+            "boundary_force_zplus",
+            "kinetic_energy",
+            "strain_energy",
+        ]
+        if self.simulation_parameters.force_source == ForceSource.RIGID_REACTION_FORCE:
+            all_outputs.append("rigid_reaction_force")
         archive = Archive(
             outputs={
                 outputs_indices_key: ["deformation_measure", "position", "stress"],
-                "all": [
-                    "boundary_force_zminus",
-                    "boundary_force_zplus",
-                    "rigid_reaction_force_0",
-                    "kinetic_energy",
-                    "strain_energy",
-                ],
+                "all": all_outputs,
             },
             output_interval=self.simulation_parameters.output_int,
         )
@@ -1052,6 +1161,22 @@ class CompressionSimulation:
         )
         return piston_info
 
+    def _get_force_source_info(self):
+        """PartInfo of the body whose rigid_reaction_force is measured."""
+        name = self.simulation_parameters.force_source_part
+        if name:
+            info = self.get_part_info(name)
+            if info is None:
+                raise RuntimeError(f"Unknown force_source_part: {name}")
+            return info
+        piston_info = self._get_piston_info()
+        if piston_info is None:
+            raise RuntimeError(
+                "force_source RIGID_REACTION_FORCE requires a piston part "
+                "or an explicit force_source_part"
+            )
+        return piston_info
+
     def _add_to_workflow_von_mises_stress(self, part_infos: list[PartInfo]):
         self._add_to_workflow_postprocess(
             part_infos, "compress", "von-mises-stress", "cauchy_stress"
@@ -1065,9 +1190,12 @@ class CompressionSimulation:
     def _add_to_workflow_force_displacement(self, part_infos: list[PartInfo]):
         job_name_base = "force-displacement"
         self._add_to_workflow_postprocess(part_infos, "compress", job_name_base)
-        self.workflow_params[f"{job_name_base}.keys"] = json.dumps(
-            ["/boundary_force_zminus"]
-        )
+        if self.simulation_parameters.force_source == ForceSource.RIGID_REACTION_FORCE:
+            source = self._get_force_source_info()
+            keys = [f"/material{source.material_index}/rigid_reaction_force"]
+        else:
+            keys = ["/boundary_force_zminus"]
+        self.workflow_params[f"{job_name_base}.keys"] = json.dumps(keys)
         self.workflow_params[f"{job_name_base}.method"] = "BoundaryForce"
         # Find the piston part — there should be exactly one
         piston_info = self._get_piston_info()

{metafold-0.12.dev1 → metafold-0.12.dev3}/metafold/simulation/run_experiment.py

@@ -56,7 +56,19 @@ JSON manifest format
 
     "simulation": {
         "max_time": 0.04,
-        "max_resolution": 512
+        "max_resolution": 512,
+
+        # Force source for force-displacement: "boundary_force" (default) or
+        # "rigid_reaction_force". When using rigid_reaction_force, optionally
+        # name the part it's measured on (defaults to the piston):
+        "force_source": "rigid_reaction_force",
+        "force_source_part": "puck",
+
+        # Per-face boundary conditions. Only the faces you list are overridden;
+        # the rest keep their defaults (x/y faces "symmetric", z faces
+        # "velocity_dirichlet"). Each value is one of: "symmetric",
+        # "velocity_dirichlet", "velocity_neumann".
+        "boundary_conditions": {"z-": "symmetric", "y+": "velocity_neumann"}
     },
 
     "workflow_steps": [
@@ -100,6 +112,7 @@ from __future__ import annotations
 
 import json
 import tempfile
+from enum import Enum
 from pathlib import Path
 from typing import Optional, Union
 from zipfile import ZipFile
@@ -234,6 +247,13 @@ def _build_simulation_parameters(sim_config: dict) -> SimulationParameters:
         obj = params
         for part in parts[:-1]:
             obj = getattr(obj, part)
+        # Manifest values for enum fields (e.g. force_source) arrive as plain
+        # strings; coerce them to the field's enum type. Non-enum fields (e.g.
+        # the boundary_conditions dict) pass through and are normalized later
+        # in create_sim_config.
+        current = getattr(obj, parts[-1], None)
+        if isinstance(current, Enum) and isinstance(value, str):
+            value = type(current)(value)
         setattr(obj, parts[-1], value)
     return params
 
@@ -289,9 +309,14 @@ def run_experiment(
         output_path=resolved_output_path,
         simulation_parameters=sim_params,
         project_id=project_id,
-        project_name=project_name,
         create_project_if_needed=not bool(project_id),
     )
+    # Only pass project_name when we have to create a project. When a
+    # project_id is supplied the project already exists, and passing the name
+    # would keep the find-or-create-by-name path alive — risking a duplicate
+    # project. simulation_name (set above) drives UPS/result naming regardless.
+    if not project_id:
+        sim_kwargs["project_name"] = project_name
     if "workflow_steps" in config:
         sim_kwargs["workflow_steps"] = _build_workflow_steps(config["workflow_steps"])
 

{metafold-0.12.dev1 → metafold-0.12.dev3}/metafold.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metafold
-Version: 0.12.dev1
+Version: 0.12.dev3
 Summary: Metafold SDK for Python
 Author-email: Metafold 3D <info@metafold3d.com>
 License: Copyright 2024 Metafold 3D

{metafold-0.12.dev1 → metafold-0.12.dev3}/metafold.egg-info/SOURCES.txt

@@ -27,5 +27,6 @@ tests/test_compression_simulation.py
 tests/test_jobs.py
 tests/test_projects.py
 tests/test_run_experiment.py
+tests/test_shear_simulation.py
 tests/test_utils.py
 tests/test_workflows.py

{metafold-0.12.dev1 → metafold-0.12.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "metafold"
-version = "0.12.dev1"
+version = "0.12.dev3"
 authors = [
     {name = "Metafold 3D", email = "info@metafold3d.com"},
 ]

{metafold-0.12.dev1 → metafold-0.12.dev3}/tests/test_compression_simulation.py

@@ -245,6 +245,55 @@ class TestBuildWorkflow:
         assert not any("force-displacement" in k for k in loaded["jobs"])
 
 
+class TestGridBounds:
+    """The grid must enclose every part, not just the representative one, so
+    nothing (e.g. an outsole below the midsole) gets clipped."""
+
+    def _grid_bounds(self, sim):
+        """Return (lower, upper) of the generated UPS grid box, in metres."""
+        root = sim.ups.getroot()
+        lower = json.loads(root.findtext(".//Grid//Box/lower"))
+        upper = json.loads(root.findtext(".//Grid//Box/upper"))
+        return lower, upper
+
+    def _prepare(self, sim, patches):
+        """Assign each part_info a patch (by unique name) and build the config."""
+        for info in sim.part_infos:
+            info.patch = patches[info.part_unique_name]
+            if hasattr(info.part, "filename"):
+                info.volume_filename = f"{info.part_unique_name}_volume.bin"
+        sim.create_sim_config()
+
+    def test_low_mesh_part_expands_grid_downward(self, sim):
+        # The regression: a mesh part (outsole) below the representative midsole
+        # must still expand the grid down. Before the fix, mesh parts were
+        # skipped and the outsole's bottom got clipped.
+        # Patch offsets/sizes are in mm; outsole bottom at -50 mm is below all
+        # other parts (incl. the piston cylinder, whose lowest point is +25 mm).
+        rep = {"size": [100.0, 100.0, 50.0], "offset": [0.0, 0.0, 0.0], "resolution": [32, 32, 16]}
+        low = {"size": [100.0, 100.0, 20.0], "offset": [0.0, 0.0, -50.0], "resolution": [32, 32, 8]}
+        patches = {
+            "piston": rep, "upper_foam": rep, "midsole": rep, "outsole": low,
+        }
+        self._prepare(sim, patches)
+        lower, _ = self._grid_bounds(sim)
+        mz = sim.simulation_parameters.margin_z
+        # grid bottom (metres) = outsole bottom (-50 mm = -0.05 m) minus margin.
+        assert lower[2] == pytest.approx(-0.05 - mz, abs=1e-6)
+
+    def test_bottom_margin_clearance_added(self, sim):
+        # Bottom (z-) clearance was previously missing entirely. With all parts
+        # flush at z=0, the grid bottom must sit margin_z below the lowest part.
+        flat = {"size": [0.1, 0.1, 0.05], "offset": [0.0, 0.0, 0.0], "resolution": [32, 32, 16]}
+        self._prepare(sim, {n: flat for n in
+                            ["piston", "upper_foam", "midsole", "outsole"]})
+        lower, _ = self._grid_bounds(sim)
+        mz = sim.simulation_parameters.margin_z
+        # Lowest part bottom is z=0 (piston cylinder sits higher), so the grid
+        # bottom is exactly -margin_z.
+        assert lower[2] == pytest.approx(-mz, abs=1e-6)
+
+
 class TestSampleAssets:
     def _make_success_workflow(self, job_names=()):
         """Return a mock workflow that is already in 'success' state."""
@@ -917,4 +966,68 @@ class TestSetupClient:
 
         assert sim.project_id == "fallback-pid"
         first_client.projects.create.assert_called_once()
-    
+
+
+class TestFindOrCreateProjectCancel:
+    """find_or_create_project should cancel a reused project's in-flight
+    workflows when asked, since the new run overwrites those results."""
+
+    @pytest.fixture
+    def patched_client_class(self, monkeypatch):
+        from metafold.simulation import compression_simulation
+        fake_class = MagicMock()
+        monkeypatch.setattr(compression_simulation, "MetafoldClient", fake_class)
+        return fake_class
+
+    def _wf(self, wid, state):
+        w = MagicMock()
+        w.id = wid
+        w.state = state
+        return w
+
+    def test_cancels_active_workflows_on_existing_project(self, patched_client_class):
+        client = patched_client_class.return_value
+        existing = MagicMock()
+        existing.id = "pid-1"
+        client.projects.list.return_value = [existing]
+        # list(q="state:pending") -> [w1]; list(q="state:started") -> [w2]
+        client.workflows.list.side_effect = [
+            [self._wf("w1", "pending")],
+            [self._wf("w2", "started")],
+        ]
+
+        pid = CompressionSimulation.find_or_create_project(
+            "existing", access_token="tok", base_url="http://x/",
+            cancel_existing_workflows=True,
+        )
+
+        assert pid == "pid-1"
+        cancelled = {c.args[0] for c in client.workflows.cancel.call_args_list}
+        assert cancelled == {"w1", "w2"}
+
+    def test_no_cancel_when_flag_off(self, patched_client_class):
+        client = patched_client_class.return_value
+        existing = MagicMock()
+        existing.id = "pid-1"
+        client.projects.list.return_value = [existing]
+
+        CompressionSimulation.find_or_create_project(
+            "existing", access_token="tok", base_url="http://x/",
+        )
+
+        client.workflows.cancel.assert_not_called()
+
+    def test_no_cancel_when_creating_new_project(self, patched_client_class):
+        client = patched_client_class.return_value
+        client.projects.list.return_value = []  # nothing existing -> create
+        created = MagicMock()
+        created.id = "new-pid"
+        client.projects.create.return_value = created
+
+        pid = CompressionSimulation.find_or_create_project(
+            "fresh", access_token="tok", base_url="http://x/",
+            cancel_existing_workflows=True,
+        )
+
+        assert pid == "new-pid"
+        client.workflows.cancel.assert_not_called()

{metafold-0.12.dev1 → metafold-0.12.dev3}/tests/test_run_experiment.py

@@ -249,6 +249,21 @@ class TestBuildSimulationParameters:
         params = _build_simulation_parameters({"max_time": 0.02})
         assert params.output_int == default.output_int
 
+    def test_enum_field_coerced_from_string(self):
+        from metafold.simulation.compression_simulation import ForceSource
+        params = _build_simulation_parameters({"force_source": "rigid_reaction_force"})
+        assert params.force_source == ForceSource.RIGID_REACTION_FORCE
+
+    def test_invalid_enum_string_raises(self):
+        with pytest.raises(ValueError):
+            _build_simulation_parameters({"force_source": "vibes"})
+
+    def test_boundary_conditions_dict_passes_through(self):
+        # String values are normalized later by create_sim_config
+        params = _build_simulation_parameters(
+            {"boundary_conditions": {"z-": "symmetric"}})
+        assert params.boundary_conditions == {"z-": "symmetric"}
+
 
 class TestRunExperiment:
     """Integration-level tests: verify run_experiment wires up
@@ -505,6 +520,35 @@ class TestRunExperimentFromZip:
         with pytest.raises(ValueError, match="experiment.json"):
             run_experiment_from_zip(zip_path, output_path=str(tmp_path / "out"))
 
+    def test_shear_simulation_params_from_manifest(self, tmp_path):
+        from metafold.simulation.compression_simulation import ForceSource
+
+        manifest = {
+            "project_name": "shear",
+            "parts": [{"type": "piston_cylinder"}],
+            "simulation": {
+                "force_source": "rigid_reaction_force",
+                "boundary_conditions": {"z-": "symmetric"},
+            },
+        }
+        zip_path = self._make_zip(tmp_path, manifest)
+        captured = {}
+        fake_sim = MagicMock(project_id="p", stl_folder=tmp_path)
+
+        def capture_sim(*args, **kwargs):
+            captured.update(kwargs)
+            return fake_sim
+
+        with (
+            patch("metafold.simulation.run_experiment.CompressionSimulation", side_effect=capture_sim),
+            patch("metafold.simulation.run_experiment.CompressionExperiment"),
+        ):
+            run_experiment_from_zip(zip_path, output_path=str(tmp_path / "out"))
+
+        params = captured["simulation_parameters"]
+        assert params.force_source == ForceSource.RIGID_REACTION_FORCE
+        assert params.boundary_conditions == {"z-": "symmetric"}
+
     def test_generator_and_created_fields_ignored(self, tmp_path):
         manifest = {
             "project_name": "grasshopper_export",

metafold-0.12.dev3/tests/test_shear_simulation.py

@@ -0,0 +1,414 @@
+import json
+import pytest
+from unittest.mock import MagicMock
+
+from metafold.simulation.compression_simulation import (
+    BoundaryCondition,
+    CompressionSimulation,
+    DEFAULT_BOUNDARY_CONDITIONS,
+    ExperimentMesh,
+    ExperimentPistonMesh,
+    ForceSource,
+    SimulationParameters,
+    WorkflowStep,
+    WorkflowStepType,
+)
+
+ALL_FACES = ["x-", "x+", "y-", "y+", "z-", "z+"]
+
+
+@pytest.fixture
+def ply_folder(tmp_path):
+    for name in ["top.ply", "mid.ply", "out.ply"]:
+        (tmp_path / name).write_bytes(b"ply\n")
+    return tmp_path
+
+
+@pytest.fixture
+def basic_parts():
+    from metafold.materials import DEFAULT_MIDSOLE_NOMINAL, DEFAULT_OUTSOLE, DEFAULT_UPPER_FOAM
+    from metafold.simulation.compression_simulation import ExperimentPistonCylinder
+    return [
+        ExperimentPistonCylinder(),
+        ExperimentMesh("upper_foam", DEFAULT_UPPER_FOAM, "top.ply"),
+        ExperimentMesh("midsole", DEFAULT_MIDSOLE_NOMINAL, "mid.ply", representative_part=True),
+        ExperimentMesh("outsole", DEFAULT_OUTSOLE, "out.ply"),
+    ]
+
+
+def _prepare_sim(parts, ply_folder, tmp_path, params=None, workflow_steps=None):
+    """Build a sim with a fixed fake patch and run create_sim_config."""
+    kwargs = {}
+    if workflow_steps is not None:
+        kwargs["workflow_steps"] = workflow_steps
+    sim = CompressionSimulation(
+        parts=parts,
+        simulation_name="t",
+        stl_folder_path=str(ply_folder),
+        output_path=str(tmp_path / "out"),
+        client=MagicMock(),
+        simulation_parameters=params or SimulationParameters(),
+        **kwargs,
+    )
+    fake_patch = {"size": [0.1, 0.1, 0.05], "offset": [0.0, 0.0, 0.0], "resolution": [32, 32, 16]}
+    for info in sim.part_infos:
+        info.patch = fake_patch
+        if hasattr(info.part, "filename"):
+            info.volume_filename = f"{info.part_unique_name}_volume.bin"
+    sim.create_sim_config()
+    return sim
+
+
+class TestSimulationParametersBoundaries:
+    """Tests for per-face boundary_conditions and force_source."""
+
+    @pytest.fixture
+    def prepared_sim(self, ply_folder, basic_parts, tmp_path, request):
+        params = getattr(request, "param", SimulationParameters())
+        return _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+
+    def _bc(self, sim, side):
+        face = sim.ups.getroot().find(f".//BoundaryConditions/Face[@side='{side}']")
+        assert face is not None, f"Missing face side='{side}'"
+        return face.find("BCType")
+
+    def _bc_var(self, sim, side):
+        return self._bc(sim, side).get("var")
+
+    def _archive_labels(self, sim):
+        return [el.get("label") for el in sim.ups.getroot().findall(".//DataArchiver/save")]
+
+    # --- defaults ---
+
+    def test_defaults(self):
+        p = SimulationParameters()
+        assert p.boundary_conditions == {
+            "x-": BoundaryCondition.SYMMETRIC,
+            "x+": BoundaryCondition.SYMMETRIC,
+            "y-": BoundaryCondition.SYMMETRIC,
+            "y+": BoundaryCondition.SYMMETRIC,
+            "z-": BoundaryCondition.VELOCITY_DIRICHLET,
+            "z+": BoundaryCondition.VELOCITY_DIRICHLET,
+        }
+        assert p.force_source == ForceSource.BOUNDARY_FORCE
+        assert p.force_source_part == ""
+
+    def test_default_dict_is_not_shared(self):
+        SimulationParameters().boundary_conditions["z-"] = BoundaryCondition.SYMMETRIC
+        assert SimulationParameters().boundary_conditions["z-"] == BoundaryCondition.VELOCITY_DIRICHLET
+        assert DEFAULT_BOUNDARY_CONDITIONS["z-"] == BoundaryCondition.VELOCITY_DIRICHLET
+
+    def test_default_lateral_is_symmetric(self, prepared_sim):
+        for side in ["x-", "x+", "y-", "y+"]:
+            assert self._bc_var(prepared_sim, side) == "symmetry"
+
+    def test_default_zminus_is_dirichlet(self, prepared_sim):
+        assert self._bc_var(prepared_sim, "z-") == "Dirichlet"
+
+    def test_zplus_default_is_dirichlet(self, prepared_sim):
+        assert self._bc_var(prepared_sim, "z+") == "Dirichlet"
+
+    def test_all_faces_present(self, prepared_sim):
+        for side in ALL_FACES:
+            assert self._bc(prepared_sim, side) is not None
+
+    def test_default_no_rigid_reaction_force_in_archive(self, prepared_sim):
+        assert "RigidReactionForce" not in self._archive_labels(prepared_sim)
+
+    # --- per-face overrides ---
+
+    def test_free_lateral_sets_dirichlet_on_xy(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(
+            boundary_conditions={
+                side: BoundaryCondition.VELOCITY_DIRICHLET
+                for side in ["x-", "x+", "y-", "y+"]
+            },
+        )
+        sim = _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+        for side in ["x-", "x+", "y-", "y+"]:
+            assert self._bc_var(sim, side) == "Dirichlet"
+
+    def test_symmetric_zminus(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(
+            boundary_conditions={"z-": BoundaryCondition.SYMMETRIC},
+        )
+        sim = _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+        assert self._bc_var(sim, "z-") == "symmetry"
+        assert self._bc_var(sim, "z+") == "Dirichlet"
+
+    def test_neumann_face(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(
+            boundary_conditions={"y+": BoundaryCondition.VELOCITY_NEUMANN},
+        )
+        sim = _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+        bc = self._bc(sim, "y+")
+        assert bc.get("var") == "Neumann"
+        assert bc.get("label") == "Velocity"
+        assert bc.get("id") == "all"
+        assert bc.findtext("value") == "[0.0, 0.0, 0.0]"
+
+    def test_partial_dict_merges_over_defaults(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(
+            boundary_conditions={"z-": BoundaryCondition.SYMMETRIC},
+        )
+        sim = _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+        # untouched faces keep their defaults
+        for side in ["x-", "x+", "y-", "y+"]:
+            assert self._bc_var(sim, side) == "symmetry"
+        assert self._bc_var(sim, "z+") == "Dirichlet"
+
+    def test_string_values_accepted(self, ply_folder, basic_parts, tmp_path):
+        # Manifest JSON delivers plain strings
+        params = SimulationParameters(
+            boundary_conditions={"z-": "symmetric", "x-": "velocity_neumann"},
+        )
+        sim = _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+        assert self._bc_var(sim, "z-") == "symmetry"
+        assert self._bc_var(sim, "x-") == "Neumann"
+
+    def test_unknown_face_raises(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(
+            boundary_conditions={"w-": BoundaryCondition.SYMMETRIC},
+        )
+        with pytest.raises(ValueError, match="Unknown boundary condition face"):
+            _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+
+    def test_invalid_condition_raises(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(boundary_conditions={"z-": "bolted"})
+        with pytest.raises(ValueError, match="bolted"):
+            _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+
+    # --- force_source = RIGID_REACTION_FORCE ---
+
+    def test_rigid_reaction_force_adds_archive_label(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(force_source=ForceSource.RIGID_REACTION_FORCE)
+        sim = _prepare_sim(basic_parts, ply_folder, tmp_path, params)
+        assert "RigidReactionForce" in self._archive_labels(sim)
+        assert "BndyForce_zminus" in self._archive_labels(sim)
+
+
+class TestForceDisplacementKeys:
+    """force-displacement workflow params reflect force_source/force_source_part."""
+
+    FD_STEPS = [WorkflowStep(WorkflowStepType.FORCE_DISPLACEMENT)]
+
+    def _built_sim(self, parts, ply_folder, tmp_path, params):
+        sim = _prepare_sim(
+            parts, ply_folder, tmp_path, params, workflow_steps=self.FD_STEPS)
+        sim.build_workflow()
+        return sim
+
+    def _fd_keys(self, sim):
+        return json.loads(sim.workflow_params["force-displacement.keys"])
+
+    def test_default_uses_boundary_force(self, ply_folder, basic_parts, tmp_path):
+        sim = self._built_sim(
+            basic_parts, ply_folder, tmp_path, SimulationParameters())
+        assert self._fd_keys(sim) == ["/boundary_force_zminus"]
+        assert sim.workflow_params["force-displacement.method"] == "BoundaryForce"
+
+    def test_rigid_reaction_defaults_to_piston(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(force_source=ForceSource.RIGID_REACTION_FORCE)
+        sim = self._built_sim(basic_parts, ply_folder, tmp_path, params)
+        # The piston is always part_infos[0], i.e. material 0
+        assert self._fd_keys(sim) == ["/material0/rigid_reaction_force"]
+
+    def test_rigid_reaction_from_named_part(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(
+            force_source=ForceSource.RIGID_REACTION_FORCE,
+            force_source_part="midsole",
+        )
+        sim = self._built_sim(basic_parts, ply_folder, tmp_path, params)
+        midsole_index = sim.get_part_info("midsole").material_index
+        assert self._fd_keys(sim) == [
+            f"/material{midsole_index}/rigid_reaction_force"
+        ]
+
+    def test_rigid_reaction_unknown_part_raises(self, ply_folder, basic_parts, tmp_path):
+        params = SimulationParameters(
+            force_source=ForceSource.RIGID_REACTION_FORCE,
+            force_source_part="flux_capacitor",
+        )
+        with pytest.raises(RuntimeError, match="flux_capacitor"):
+            self._built_sim(basic_parts, ply_folder, tmp_path, params)
+
+
+class TestShearUPS:
+    """Verify that CompressionSimulation generates a UPS structurally identical
+    to the reference shear test script for the same inputs.
+
+    The grid dimensions depend on the sampled mesh patch and can't be matched
+    exactly without running the mesh sampling job, so we test every structural
+    property the script controls: BCs, archive outputs, contact, materials,
+    viscoelastic modes, and time parameters.
+    """
+
+    PISTON_MATERIAL = {
+        "density": 1730.0,
+        "thermal_conductivity": 45,
+        "specific_heat": 4.8e-4,
+        "constitutive_model": {
+            "type": "rigid",
+            "params": {"shear_modulus": 2667.0e6, "bulk_modulus": 8000.0e6},
+        },
+    }
+
+    PUCK_MATERIAL = {
+        "density": 130.0,
+        "thermal_conductivity": 45,
+        "specific_heat": 4.8e-4,
+        "constitutive_model": {
+            "type": "Maxwell_Weichert",
+            "params": {
+                "bulk_modulus": 600000,
+                "terminal_shear_modulus": 200000,
+                "viscoelastic_series": [
+                    {"mode": "mode1", "relaxation_time": 0.005, "partial_shear_modulus": 100000},
+                    {"mode": "mode2", "relaxation_time": 0.01,  "partial_shear_modulus": 100000},
+                ],
+            },
+        },
+    }
+
+    SHEAR_VELOCITY = [
+        [0.0,    0, 0,      0.0],
+        [0.0025, 0, 0,     -0.25],
+        [0.01,   0, 1.732, -1.0],
+        [0.02,   0, 1.732, -1.0],
+    ]
+
+    @pytest.fixture
+    def shear_sim(self, tmp_path):
+        from metafold.materials import Material
+        piston_mat = Material.from_dict(self.PISTON_MATERIAL)
+        puck_mat = Material.from_dict(self.PUCK_MATERIAL)
+
+        parts = [
+            ExperimentPistonMesh(
+                name="piston_top",
+                filename="piston_top.stl",
+                material=piston_mat,
+                velocity=self.SHEAR_VELOCITY,
+            ),
+            ExperimentMesh("puck", puck_mat, "puck.stl", representative_part=True),
+        ]
+
+        sim_params = SimulationParameters(
+            max_time=0.013,
+            init_time=0.0,
+            delt_min=0.0,
+            delt_max=0.001,
+            timestep_multiplier=0.4,
+            output_int=0.00075,
+            boundary_conditions={
+                side: BoundaryCondition.VELOCITY_DIRICHLET for side in ALL_FACES
+            },
+            force_source=ForceSource.RIGID_REACTION_FORCE,
+        )
+
+        for name in ["piston_top.stl", "puck.stl"]:
+            (tmp_path / name).write_bytes(b"ply\n")
+
+        sim = CompressionSimulation(
+            parts=parts,
+            simulation_name="puck_5_A",
+            stl_folder_path=str(tmp_path),
+            output_path=str(tmp_path / "out"),
+            client=MagicMock(),
+            simulation_parameters=sim_params,
+        )
+
+        # Use a fixed patch (grid dims vary with mesh; we only verify structure)
+        fake_patch = {"size": [0.1, 0.1, 0.03], "offset": [-0.05, -0.05, 0.0], "resolution": [64, 64, 20]}
+        for info in sim.part_infos:
+            info.patch = fake_patch
+            if hasattr(info.part, "filename"):
+                info.volume_filename = f"{info.part_unique_name}_volume.bin"
+        sim.create_sim_config()
+        return sim
+
+    def _root(self, shear_sim):
+        return shear_sim.ups.getroot()
+
+    def _bc(self, shear_sim, side):
+        face = self._root(shear_sim).find(f".//BoundaryConditions/Face[@side='{side}']")
+        assert face is not None, f"Missing face side='{side}'"
+        return face.find("BCType")
+
+    def _archive_labels(self, shear_sim):
+        return [el.get("label") for el in self._root(shear_sim).findall(".//DataArchiver/save")]
+
+    # --- time parameters ---
+
+    def test_max_time(self, shear_sim):
+        assert self._root(shear_sim).findtext(".//Time/maxTime") == "0.013"
+
+    def test_timestep_multiplier(self, shear_sim):
+        assert self._root(shear_sim).findtext(".//Time/timestep_multiplier") == "0.4"
+
+    def test_output_interval(self, shear_sim):
+        assert self._root(shear_sim).findtext(".//DataArchiver/outputInterval") == "0.00075"
+
+    # --- boundary conditions ---
+
+    def test_lateral_faces_are_dirichlet(self, shear_sim):
+        for side in ["x-", "x+", "y-", "y+"]:
+            assert self._bc(shear_sim, side).get("var") == "Dirichlet", f"side={side}"
+
+    def test_zminus_is_dirichlet(self, shear_sim):
+        assert self._bc(shear_sim, "z-").get("var") == "Dirichlet"
+
+    def test_zplus_is_dirichlet(self, shear_sim):
+        assert self._bc(shear_sim, "z+").get("var") == "Dirichlet"
+
+    # --- archive outputs ---
+
+    def test_archive_includes_rigid_reaction_force(self, shear_sim):
+        assert "RigidReactionForce" in self._archive_labels(shear_sim)
+
+    def test_archive_includes_boundary_forces(self, shear_sim):
+        labels = self._archive_labels(shear_sim)
+        assert "BndyForce_zminus" in labels
+        assert "BndyForce_zplus" in labels
+
+    def test_archive_includes_particle_data(self, shear_sim):
+        labels = self._archive_labels(shear_sim)
+        assert "p.x" in labels
+        assert "p.stress" in labels
+
+    # --- contact ---
+
+    def test_contact_type_is_rigid(self, shear_sim):
+        contact = self._root(shear_sim).find(".//contact")
+        assert contact is not None
+        assert contact.findtext("type") == "rigid"
+
+    def test_contact_has_velocity_file(self, shear_sim):
+        contact = self._root(shear_sim).find(".//contact")
+        assert contact.findtext("filename") == "velocity_piston_top.txt"
+
+    def test_contact_mu_is_zero(self, shear_sim):
+        contact = self._root(shear_sim).find(".//contact")
+        assert float(contact.findtext("mu")) == 0.0
+
+    def test_contact_direction(self, shear_sim):
+        contact = self._root(shear_sim).find(".//contact")
+        assert contact.findtext("direction") == "[1, 1, 1]"
+
+    # --- viscoelastic modes ---
+
+    def test_viscoelastic_modes_are_xml_elements_not_json(self, shear_sim):
+        vs = self._root(shear_sim).find(".//viscoelastic_series")
+        assert vs is not None
+        modes = vs.findall("mode")
+        assert len(modes) == 2
+
+    def test_viscoelastic_mode_names(self, shear_sim):
+        modes = self._root(shear_sim).findall(".//viscoelastic_series/mode")
+        names = [m.get("name") for m in modes]
+        assert names == ["mode1", "mode2"]
+
+    def test_viscoelastic_relaxation_times(self, shear_sim):
+        modes = self._root(shear_sim).findall(".//viscoelastic_series/mode")
+        times = [float(m.findtext("relaxation_time")) for m in modes]
+        assert times == [0.005, 0.01]