feat(motor): tank geometry union + fluid density function + tank_kind guard

Paired API-side work for the jarvis tank/fluid migration (branch
feat/tank-fluid-schema-migration in jarvis-ts). Mirrors what that repo
now sends on the wire:

Schema (src/models/sub/tanks.py):
- MotorTank.geometry is a discriminated union on geometry_kind:
  * custom       → legacy piecewise (TankGeometry)
  * cylindrical  → CylindricalTank(radius, height, spherical_caps)
  * spherical    → SphericalTank(radius)
- TankFluids.density accepts float or List[(T_K, rho)] temperature
  samples; pressure dependence deferred.
- New validate_tank_kind_fields model_validator mirrors the
  validate_dry_inertia_for_kind pattern from motor.py — rejects
  payloads whose tank_kind omits required kind-specific fields at
  the API boundary with a kind-named 422 instead of letting rocketpy
  crash deeper in construction.
- discretize is now optional (defaults to 100).

Service (src/services/motor.py):
- _build_rocketpy_tank_geometry dispatches on geometry_kind to
  TankGeometry/CylindricalTank/SphericalTank.
- _build_rocketpy_fluid instantiates a real rocketpy.Fluid and wraps
  sampled density in a 1D Function-of-temperature callable; scalars
  pass through. (Eliminates the duck-typed Pydantic-into-rocketpy
  pattern that worked by accident.)

Inverse path (src/services/flight.py):
- _extract_fluid_density collapses Function-valued density back to a
  scalar at rocketpy's reference state (273.15 K, 101325 Pa) — lossy
  round-trip is documented; samples-roundtrip not supported in this
  iteration.
- Geometry inverse always emits the 'custom' segment list shape; all
  three rocketpy geometry subclasses expose a piecewise .geometry dict
  so one code path covers them uniformly.

Tests:
- test_motors_route.py: 8 new cases covering each geometry_kind,
  sampled density, invalid discriminator, and all four tank_kind guard
  paths (MASS / MASS_FLOW / LEVEL / ULLAGE missing sub-fields).
- tests/unit/test_services/test_motor_service.py: new suite exercising
  the adapter end-to-end against real rocketpy for each
  geometry×variant combination plus sampled density roundtrip.

Routes (src/routes/motor.py):
- POST /motors docstring gained an example payload showing the
  discriminated geometry union and sampled density shape.

Gitignore:
- Added .context and .pylint.d/ to keep local tooling artifacts out
  of the tree.

Full suite: 173/173 pass.

Author: aasitvora99

.gitignore

@@ -160,4 +160,10 @@ cython_debug/
 #.idea/
 
 # VSCode config
-.vscode/
+.vscode/
+
+# context specific ignores
+.context
+
+# lint
+.pylint.d/

src/models/sub/tanks.py

@@ -1,6 +1,7 @@
 from enum import Enum
-from typing import Optional, Tuple, List
-from pydantic import BaseModel
+from typing import Annotated, List, Literal, Optional, Tuple, Union
+
+from pydantic import BaseModel, Field, model_validator
 
 
 class TankKinds(str, Enum):
@@ -10,14 +11,75 @@ class TankKinds(str, Enum):
     ULLAGE: str = "ULLAGE"
 
 
+# Scalar density keeps the legacy behaviour (constant kg/m^3).
+# A list of (temperature_K, density_kg_per_m3) samples enables
+# temperature-dependent density — required for realistic LOX / N2O
+# modelling. Pressure dependence is out of scope for this iteration.
+DensityInput = Union[float, List[Tuple[float, float]]]
+
+
 class TankFluids(BaseModel):
     name: str
-    density: float
+    density: DensityInput
+
+
+# --- Tank geometry discriminated union ----------------------------------
+# RocketPy ships three concrete geometry classes. We mirror them as a
+# discriminated Pydantic union keyed on `geometry_kind`. `custom` is the
+# generic piecewise form (original API shape); `cylindrical` and
+# `spherical` map to `rocketpy.motors.CylindricalTank` and
+# `SphericalTank` respectively.
+
+
+class CustomTankGeometry(BaseModel):
+    geometry_kind: Literal["custom"] = "custom"
+    geometry: List[Tuple[Tuple[float, float], float]]
+
+
+class CylindricalTankGeometry(BaseModel):
+    geometry_kind: Literal["cylindrical"] = "cylindrical"
+    radius: float
+    height: float
+    spherical_caps: bool = False
+
+
+class SphericalTankGeometry(BaseModel):
+    geometry_kind: Literal["spherical"] = "spherical"
+    radius: float
+
+
+TankGeometryInput = Annotated[
+    Union[
+        CustomTankGeometry,
+        CylindricalTankGeometry,
+        SphericalTankGeometry,
+    ],
+    Field(discriminator="geometry_kind"),
+]
+
+
+# Map tank_kind → tuple of MotorTank field names that rocketpy's
+# corresponding Tank subclass requires. The validator below rejects
+# payloads that omit any of them so the API returns 422 instead of
+# letting rocketpy crash during motor construction.
+_REQUIRED_FIELDS_BY_TANK_KIND = {
+    TankKinds.MASS_FLOW: (
+        "initial_liquid_mass",
+        "initial_gas_mass",
+        "liquid_mass_flow_rate_in",
+        "liquid_mass_flow_rate_out",
+        "gas_mass_flow_rate_in",
+        "gas_mass_flow_rate_out",
+    ),
+    TankKinds.LEVEL: ("liquid_height",),
+    TankKinds.ULLAGE: ("ullage",),
+    TankKinds.MASS: ("liquid_mass", "gas_mass"),
+}
 
 
 class MotorTank(BaseModel):
     # Required parameters
-    geometry: List[Tuple[Tuple[float, float], float]]
+    geometry: TankGeometryInput
     gas: TankFluids
     liquid: TankFluids
     flux_time: Tuple[float, float]
@@ -48,3 +110,20 @@ class MotorTank(BaseModel):
 
     # Computed parameters
     tank_kind: TankKinds = TankKinds.MASS_FLOW
+
+    @model_validator(mode='after')
+    def validate_tank_kind_fields(self):
+        # Mirrors the validate_dry_inertia_for_kind pattern used on
+        # MotorModel: reject incoherent payloads at the API boundary
+        # instead of letting rocketpy crash during Tank construction.
+        missing = [
+            field
+            for field in _REQUIRED_FIELDS_BY_TANK_KIND[self.tank_kind]
+            if getattr(self, field) is None
+        ]
+        if missing:
+            raise ValueError(
+                f"tank_kind={self.tank_kind.value} requires: "
+                f"{', '.join(missing)}"
+            )
+        return self

src/routes/motor.py

@@ -36,6 +36,31 @@ async def create_motor(
 
     ## Args
     ``` models.Motor JSON ```
+
+    For liquid/hybrid motors the `tanks` field supports three geometry
+    kinds via the `geometry_kind` discriminator and a scalar-or-sampled
+    fluid `density`:
+
+    ```
+    {
+      "motor_kind": "LIQUID",
+      ...
+      "tanks": [{
+        "geometry": {
+          "geometry_kind": "cylindrical",    // or "spherical", "custom"
+          "radius": 0.1, "height": 0.5
+        },
+        "liquid": {
+          "name": "LOX",
+          "density": [[90.0, 1141.0], [120.0, 1091.0]]   // or scalar
+        },
+        "gas": {"name": "N2", "density": 1.2},
+        "tank_kind": "LEVEL",
+        "liquid_height": 0.25,
+        ...
+      }]
+    }
+    ```
     """
     with tracer.start_as_current_span("create_motor"):
         return await controller.post_motor(motor)

src/services/flight.py

@@ -224,6 +224,22 @@ def _to_float(value) -> float:
             case _:
                 return float(value)
 
+    @staticmethod
+    def _extract_fluid_density(fluid):
+        """Project a rocketpy Fluid's density back onto the API schema.
+
+        The API accepts either a scalar or a list of (T_K, density)
+        samples. Rocketpy may store density as either a raw scalar or a
+        ``Function`` wrapping a 2D ``(T, P) -> density`` callable. A
+        full sample round-trip is not supported in this iteration;
+        Function-valued densities are collapsed to a scalar evaluated
+        at rocketpy's default reference (273.15 K, 101325 Pa).
+        """
+        density = fluid.density
+        if isinstance(density, Function):
+            return float(density(273.15, 101325))
+        return density
+
     @staticmethod
     def _extract_tanks(motor) -> list[MotorTank]:
         tanks: list[MotorTank] = []
@@ -240,20 +256,29 @@ def _extract_tanks(motor) -> list[MotorTank]:
                 case _:
                     tank_kind = TankKinds.MASS_FLOW
 
-            geometry = [
+            # Geometry round-trip is lossy: even if the client originally
+            # sent a cylindrical/spherical geometry, we discretise it back
+            # to the generic piecewise form on read. Every rocketpy tank
+            # geometry exposes its internal piecewise dict via
+            # `tank.geometry.geometry`, so this path covers all three
+            # geometry subclasses uniformly.
+            geometry_segments = [
                 (bounds, float(func(0)))
                 for bounds, func in tank.geometry.geometry.items()
             ]
 
             data: dict = {
-                "geometry": geometry,
+                "geometry": {
+                    "geometry_kind": "custom",
+                    "geometry": geometry_segments,
+                },
                 "gas": TankFluids(
                     name=tank.gas.name,
-                    density=tank.gas.density,
+                    density=FlightService._extract_fluid_density(tank.gas),
                 ),
                 "liquid": TankFluids(
                     name=tank.liquid.name,
-                    density=tank.liquid.density,
+                    density=FlightService._extract_fluid_density(tank.liquid),
                 ),
                 "flux_time": tank.flux_time,
                 "position": position,

tests/unit/test_routes/conftest.py

@@ -36,51 +36,117 @@ def stub_motor_dump():
 
 @pytest.fixture
 def stub_tank_dump():
+    # Base fixture defaults to MASS_FLOW (matches MotorTank's own default)
+    # so the tank validates standalone. Sub-variant fixtures below switch
+    # tank_kind and populate only the fields that variant requires.
     tank = MotorTank(
-        geometry=[[(0, 0), 0]],
+        geometry={
+            'geometry_kind': 'custom',
+            'geometry': [[(0, 0), 0]],
+        },
         gas=TankFluids(name='gas', density=0),
         liquid=TankFluids(name='liquid', density=0),
         flux_time=(0, 0),
         position=0,
         discretize=0,
         name='tank',
+        gas_mass_flow_rate_in=0,
+        gas_mass_flow_rate_out=0,
+        liquid_mass_flow_rate_in=0,
+        liquid_mass_flow_rate_out=0,
+        initial_liquid_mass=0,
+        initial_gas_mass=0,
     )
     tank_json = tank.model_dump_json()
     return json.loads(tank_json)
 
 
 @pytest.fixture
-def stub_level_tank_dump(stub_tank_dump):
-    stub_tank_dump.update({'tank_kind': TankKinds.LEVEL, 'liquid_height': 0})
+def stub_cylindrical_tank_dump(stub_tank_dump):
+    stub_tank_dump['geometry'] = {
+        'geometry_kind': 'cylindrical',
+        'radius': 0.1,
+        'height': 0.5,
+        'spherical_caps': False,
+    }
     return stub_tank_dump
 
 
 @pytest.fixture
-def stub_mass_flow_tank_dump(stub_tank_dump):
+def stub_spherical_tank_dump(stub_tank_dump):
+    stub_tank_dump['geometry'] = {
+        'geometry_kind': 'spherical',
+        'radius': 0.2,
+    }
+    return stub_tank_dump
+
+
+@pytest.fixture
+def stub_tank_with_sampled_density_dump(stub_tank_dump):
+    stub_tank_dump['liquid'] = {
+        'name': 'LOX',
+        'density': [[90.0, 1141.0], [120.0, 1091.0], [150.0, 1021.0]],
+    }
+    return stub_tank_dump
+
+
+@pytest.fixture
+def stub_level_tank_dump(stub_tank_dump):
+    # Switch out of the MASS_FLOW defaults into LEVEL, clearing the
+    # unused MASS_FLOW fields so the kind-specific validator passes.
     stub_tank_dump.update(
         {
-            'tank_kind': TankKinds.MASS_FLOW,
-            'gas_mass_flow_rate_in': 0,
-            'gas_mass_flow_rate_out': 0,
-            'liquid_mass_flow_rate_in': 0,
-            'liquid_mass_flow_rate_out': 0,
-            'initial_liquid_mass': 0,
-            'initial_gas_mass': 0,
+            'tank_kind': TankKinds.LEVEL,
+            'liquid_height': 0,
+            'gas_mass_flow_rate_in': None,
+            'gas_mass_flow_rate_out': None,
+            'liquid_mass_flow_rate_in': None,
+            'liquid_mass_flow_rate_out': None,
+            'initial_liquid_mass': None,
+            'initial_gas_mass': None,
         }
     )
     return stub_tank_dump
 
 
+@pytest.fixture
+def stub_mass_flow_tank_dump(stub_tank_dump):
+    # stub_tank_dump already includes all MASS_FLOW fields.
+    stub_tank_dump['tank_kind'] = TankKinds.MASS_FLOW
+    return stub_tank_dump
+
+
 @pytest.fixture
 def stub_ullage_tank_dump(stub_tank_dump):
-    stub_tank_dump.update({'tank_kind': TankKinds.ULLAGE, 'ullage': 0})
+    stub_tank_dump.update(
+        {
+            'tank_kind': TankKinds.ULLAGE,
+            'ullage': 0,
+            'gas_mass_flow_rate_in': None,
+            'gas_mass_flow_rate_out': None,
+            'liquid_mass_flow_rate_in': None,
+            'liquid_mass_flow_rate_out': None,
+            'initial_liquid_mass': None,
+            'initial_gas_mass': None,
+        }
+    )
     return stub_tank_dump
 
 
 @pytest.fixture
 def stub_mass_tank_dump(stub_tank_dump):
     stub_tank_dump.update(
-        {'tank_kind': TankKinds.MASS, 'liquid_mass': 0, 'gas_mass': 0}
+        {
+            'tank_kind': TankKinds.MASS,
+            'liquid_mass': 0,
+            'gas_mass': 0,
+            'gas_mass_flow_rate_in': None,
+            'gas_mass_flow_rate_out': None,
+            'liquid_mass_flow_rate_in': None,
+            'liquid_mass_flow_rate_out': None,
+            'initial_liquid_mass': None,
+            'initial_gas_mass': None,
+        }
     )
     return stub_tank_dump