odecast 0.1.0__py3-none-any.whl

odecast/__init__.py

@@ -0,0 +1,10 @@
+"""
+Odecast: A DSL for ordinary differential equations
+"""
+
+from .symbols import t
+from .api import var, solve, BC
+from .equation import Eq
+
+__version__ = "0.1.0"
+__all__ = ["t", "var", "Eq", "solve", "BC"]

odecast/analyze.py

@@ -0,0 +1,132 @@
+"""
+Analysis functions for ODEs - order inference, validation, etc.
+"""
+
+from typing import Set, List, Dict
+import sympy as sp
+from .symbols import Variable, Derivative, as_sympy
+from .equation import Eq
+from .errors import OrderMismatchError
+
+
+def collect_variables(eqs: List[Eq]) -> Set[Variable]:
+    """
+    Collect all variables used in the given equations.
+
+    Args:
+        eqs: List of equations to analyze
+
+    Returns:
+        Set of Variable objects found in the equations
+    """
+    variables = set()
+
+    for eq in eqs:
+        # Convert equation to SymPy and walk the expression tree
+        sympy_eq = eq.sympy()
+
+        # Get all functions in the equation (these correspond to our variables)
+        functions = sympy_eq.atoms(sp.Function)
+
+        # Map back to our Variable objects by walking the original expressions
+        _collect_variables_from_expr(eq.lhs, variables)
+        _collect_variables_from_expr(eq.rhs, variables)
+
+    return variables
+
+
+def _collect_variables_from_expr(expr, variables: Set[Variable]):
+    """Helper function to recursively collect variables from an expression."""
+    from .symbols import Expression  # Avoid circular import
+
+    if isinstance(expr, Variable):
+        variables.add(expr)
+    elif isinstance(expr, Derivative):
+        variables.add(expr.variable)
+    elif isinstance(expr, Expression):
+        _collect_variables_from_expr(expr.left, variables)
+        _collect_variables_from_expr(expr.right, variables)
+    # For other types (numbers, SymPy expressions), do nothing
+
+
+def infer_orders(eqs: List[Eq]) -> Dict[Variable, int]:
+    """
+    Infer the maximum derivative order for each variable from the equations.
+
+    Args:
+        eqs: List of equations to analyze
+
+    Returns:
+        Dictionary mapping each variable to its maximum derivative order
+    """
+    orders = {}
+
+    for eq in eqs:
+        # Analyze both sides of the equation
+        _infer_orders_from_expr(eq.lhs, orders)
+        _infer_orders_from_expr(eq.rhs, orders)
+
+    return orders
+
+
+def _infer_orders_from_expr(expr, orders: Dict[Variable, int]):
+    """Helper function to recursively infer orders from an expression."""
+    from .symbols import Expression  # Avoid circular import
+
+    if isinstance(expr, Variable):
+        # Variable itself has order 0
+        current_order = orders.get(expr, 0)
+        orders[expr] = max(current_order, 0)
+    elif isinstance(expr, Derivative):
+        # Derivative has the specified order
+        current_order = orders.get(expr.variable, 0)
+        orders[expr.variable] = max(current_order, expr.order)
+    elif isinstance(expr, Expression):
+        _infer_orders_from_expr(expr.left, orders)
+        _infer_orders_from_expr(expr.right, orders)
+    # For other types (numbers, SymPy expressions), do nothing
+
+
+def resolve_orders(
+    variables: List[Variable], inferred: Dict[Variable, int]
+) -> Dict[Variable, int]:
+    """
+    Resolve final orders by checking intent_order against inferred orders.
+
+    Args:
+        variables: List of variables to resolve orders for
+        inferred: Dictionary of inferred orders from equations
+
+    Returns:
+        Dictionary mapping each variable to its resolved order
+
+    Raises:
+        OrderMismatchError: If intent_order is set but is less than inferred order
+    """
+    resolved = {}
+
+    for var in variables:
+        inferred_order = inferred.get(var, 0)
+
+        if var.intent_order is not None:
+            if inferred_order > var.intent_order:
+                raise OrderMismatchError(
+                    f"Variable '{var.name}' was declared with order {var.intent_order}, "
+                    f"but equations use derivatives up to order {inferred_order}"
+                )
+            # Use the maximum of intent_order and inferred_order
+            resolved[var] = max(var.intent_order, inferred_order)
+        else:
+            # Use inferred order
+            resolved[var] = inferred_order
+
+    return resolved
+
+
+def analyze_equation(equation):
+    """
+    Analyze an equation to determine properties like order, variables involved, etc.
+
+    This is a placeholder for future implementation.
+    """
+    raise NotImplementedError("analyze_equation will be implemented in later playbooks")

odecast/api.py

@@ -0,0 +1,253 @@
+"""
+Main APIs for odecast
+"""
+
+from typing import Dict, Any, Optional, Union, List
+from .symbols import t, Variable
+from .equation import Eq
+
+
+def var(
+    name: str, order: Optional[int] = None, shape: Optional[tuple] = None
+) -> Variable:
+    """
+    Create a dependent variable for use in differential equations.
+
+    The variable represents an unknown function y(t) where t is the independent variable.
+    You can create derivatives using the .d(n) method.
+
+    Args:
+        name: Name of the variable (e.g., "y", "x", "theta")
+        order: Maximum order of derivatives expected (optional, for validation).
+               If specified and equations use higher-order derivatives, an
+               OrderMismatchError will be raised.
+        shape: Shape tuple for vector/matrix variables (e.g., (3,) for 3D vector,
+               (2, 2) for 2x2 matrix). None for scalar variables.
+
+    Returns:
+        Variable object that supports:
+        - Arithmetic operations: y + z, 2*y, y/3, etc.
+        - Derivative notation: y.d() for y', y.d(2) for y'', etc.
+        - Use in equations: Eq(y.d(2) + y, 0)
+        - Component access for vectors: u[0], u[1] for vector components
+        - Vectorized operations: u.d() + 2*u for vector equations
+
+    Examples:
+        >>> y = var("y")           # Create scalar variable y(t)
+        >>> y.d()                  # First derivative y'(t)
+        >>> y.d(2)                 # Second derivative y''(t)
+        >>> Eq(y.d(2) + y, 0)     # Simple harmonic oscillator
+
+        >>> u = var("u", shape=(2,))  # Create 2D vector variable u(t)
+        >>> u[0]                      # First component u[0](t)
+        >>> u.d()                     # Vector derivative u'(t)
+        >>> Eq(u.d() + u, 0)         # Vector equation u' + u = 0
+
+        >>> z = var("z", order=1)  # Declare z as first-order only
+        >>> Eq(z.d() - z, 0)       # Valid: uses only first derivative
+        >>> Eq(z.d(2) + z, 0)      # Would raise OrderMismatchError
+    """
+    return Variable(name, order, shape)
+
+
+def solve(equation, *, ivp=None, bvp=None, tspan=None, backend=None, **kwargs):
+    """
+    Solve an ordinary differential equation or system of ODEs.
+
+    This is the main entry point for solving differential equations. It supports
+    both symbolic and numeric solutions through different backends.
+
+    Args:
+        equation: Single Eq object or list of Eq objects representing the ODE system
+        ivp: Dictionary of initial conditions for initial value problems (IVP).
+             Keys can be Variable objects (for y(t0)) or Derivative objects (for y'(t0)).
+             Example: {y: 1.0, y.d(): 0.0} for y(0)=1, y'(0)=0
+        bvp: List of boundary conditions for boundary value problems (BVP).
+             Currently not implemented - will be available in future versions.
+        tspan: Tuple of (t_start, t_end) for numeric solutions.
+               Required for scipy backend, ignored for sympy backend.
+        backend: Solution backend to use:
+                 - "scipy": Numeric integration using SciPy (default)
+                 - "sympy": Symbolic solution using SymPy
+                 - "auto": Try SymPy first, fall back to SciPy if needed
+                 - "scipy_bvp": BVP solver (not yet implemented)
+        **kwargs: Additional backend-specific options:
+                  For scipy: method, rtol, atol, max_step, etc.
+
+    Returns:
+        Solution object that depends on the backend:
+        - SolutionIVP: For numeric solutions, supports sol[y], sol[y.d()], etc.
+        - SolutionExpr: For symbolic solutions, supports sol.as_expr(y)
+
+    Raises:
+        MissingInitialConditionError: When required initial conditions are missing
+        OverdeterminedConditionsError: When too many initial conditions provided
+        OrderMismatchError: When declared variable order conflicts with equation usage
+        BackendError: When the chosen backend cannot solve the equation
+        ValueError: When required arguments are missing (e.g., tspan for scipy)
+
+    Examples:
+        Numeric solution of second-order ODE:
+        >>> y = var("y")
+        >>> eq = Eq(y.d(2) + 0.3*y.d() + y, 0)
+        >>> sol = solve(eq, ivp={y: 1.0, y.d(): 0.0}, tspan=(0, 10))
+        >>> y_values = sol[y]         # Get y(t) values
+        >>> yprime_values = sol[y.d()] # Get y'(t) values
+
+        Symbolic solution:
+        >>> eq = Eq(y.d(2) + y, 0)
+        >>> sol = solve(eq, backend="sympy")
+        >>> expr = sol.as_expr(y)    # Get SymPy expression
+
+        Coupled system:
+        >>> y, z = var("y"), var("z")
+        >>> eq1 = Eq(y.d(2) + z, 0)
+        >>> eq2 = Eq(z.d() - y, 0)
+        >>> sol = solve([eq1, eq2], ivp={y: 1.0, y.d(): 0.0, z: 0.0}, tspan=(0, 5))
+    """
+    from .analyze import collect_variables, infer_orders, resolve_orders
+    from .validate import validate_ivp
+    from .reduce import build_state_map, isolate_highest_derivatives, make_rhs
+    from .compile import lambdify_rhs, lambdify_jac
+    from .backends.scipy_ivp import ScipyIVPBackend, convert_ivp_to_state_vector
+    from .equation import expand_vector_equations
+    import sympy as sp
+
+    # Normalize equations to list
+    eqs = [equation] if isinstance(equation, Eq) else list(equation)
+
+    # Expand vector equations to component equations
+    eqs = expand_vector_equations(eqs)
+
+    # Step 1: Analyze - infer orders and resolve
+    variables = collect_variables(eqs)
+    inferred_orders = infer_orders(eqs)
+    orders = resolve_orders(list(variables), inferred_orders)
+
+    # Route to appropriate backend
+    if backend is None:
+        backend = "scipy"  # Default to scipy for IVP
+
+    if backend == "auto":
+        # Try SymPy first, fall back to SciPy on failure
+        try:
+            from .backends.sympy_backend import SymPyBackend
+
+            backend_instance = SymPyBackend()
+            solution = backend_instance.solve(
+                equations=eqs, t_symbol=t.symbol, **kwargs
+            )
+            return solution
+        except Exception:
+            # Fall back to SciPy backend
+            backend = "scipy"
+
+    if backend == "scipy":
+        if ivp is None:
+            raise ValueError("IVP conditions required for scipy backend")
+        if tspan is None:
+            raise ValueError("tspan required for scipy backend")
+
+        # Step 2: Validate IVP
+        t0 = tspan[0]
+        validate_ivp(orders, ivp, t0)
+
+        # Step 3: Reduce to first-order system
+        mapping = build_state_map(orders)
+        highest_rules = isolate_highest_derivatives(eqs, orders)
+        f_sym_vec, jac_sym = make_rhs(t.symbol, mapping, highest_rules)
+
+        # Step 4: Convert IVP to state vector
+        x0 = convert_ivp_to_state_vector(ivp, mapping)
+
+        # Step 5: Compile to numerical functions
+        # Determine state symbols
+        n_states = len(x0)
+        state_syms = [sp.Symbol(f"x{i}") for i in range(n_states)]
+
+        f_compiled = lambdify_rhs(f_sym_vec, t.symbol, state_syms)
+        jac_compiled = (
+            lambdify_jac(jac_sym, t.symbol, state_syms) if jac_sym is not None else None
+        )
+
+        # Step 6: Solve using SciPy backend
+        backend_instance = ScipyIVPBackend()
+        solution = backend_instance.solve(
+            f_compiled=f_compiled,
+            jac_compiled=jac_compiled,
+            x0=x0,
+            t0=t0,
+            tspan=tspan,
+            mapping=mapping,
+            options=kwargs,
+        )
+
+        return solution
+
+    elif backend == "sympy":
+        # SymPy backend for symbolic solutions
+        from .backends.sympy_backend import SymPyBackend
+
+        # Create SymPy backend instance
+        backend_instance = SymPyBackend()
+        solution = backend_instance.solve(equations=eqs, t_symbol=t.symbol, **kwargs)
+
+        return solution
+
+    elif backend == "scipy_bvp":
+        # Import BVP backend
+        from .backends.scipy_bvp import ScipyBVPBackend
+
+        # Create BVP backend instance
+        backend_instance = ScipyBVPBackend()
+
+        # For now, just raise NotImplementedError as the actual implementation
+        # will come in Milestone 5
+        raise NotImplementedError("BVP backend will be implemented in Milestone 5")
+
+    else:
+        raise ValueError(f"Unknown backend: {backend}")
+
+
+class BC:
+    """
+    Boundary condition for boundary value problems (BVP).
+
+    Boundary conditions specify the value of a variable or its derivative
+    at specific points in the domain. This is used for BVP problems where
+    conditions are given at multiple points rather than all at the initial point.
+
+    Args:
+        variable: The variable or derivative to constrain (Variable or Derivative object)
+        t: The time/position where the condition applies
+        value: The required value at that position
+
+    Examples:
+        >>> y = var("y")
+        >>> bc1 = BC(y, t=0, value=0)      # y(0) = 0
+        >>> bc2 = BC(y, t=1, value=1)      # y(1) = 1
+        >>> bc3 = BC(y.d(), t=0, value=0)  # y'(0) = 0
+
+        BVP problem:
+        >>> eq = Eq(y.d(2) + y, 0)
+        >>> sol = solve(eq, bvp=[bc1, bc2], tspan=(0, 1), backend="scipy_bvp")
+
+    Note:
+        BVP solving is not yet implemented and will be available in future versions.
+    """
+
+    def __init__(self, variable, *, t=None, value=None):
+        """
+        Create a boundary condition.
+
+        Args:
+            variable: The variable or derivative to constrain
+            t: The time/position where condition applies
+            value: The value at that position
+        """
+        self.variable = variable
+        self.t = t
+        self.value = value
+
+    def __repr__(self):
+        return f"BC({self.variable}, t={self.t}, value={self.value})"

odecast/backends/__init__.py

@@ -0,0 +1,5 @@
+"""
+Backend implementations for solving ODEs
+"""
+
+# This package contains different solver backends

odecast/backends/scipy_bvp.py

@@ -0,0 +1,46 @@
+"""
+SciPy-based backend for solving boundary value problems
+"""
+
+from typing import Any, List, Dict
+from ..api import BC
+
+
+class ScipyBVPBackend:
+    """
+    Backend for solving boundary value problems using SciPy's solve_bvp.
+
+    This backend will handle two-point boundary value problems where
+    conditions are specified at multiple points in the domain.
+    """
+
+    def solve(
+        self, system: Any, bvp: List[BC], tspan: tuple, options: Dict = None
+    ) -> Any:
+        """
+        Solve a boundary value problem.
+
+        Args:
+            system: First-order system representation
+            bvp: List of boundary conditions
+            tspan: Integration domain (start, end)
+            options: Additional solver options
+
+        Returns:
+            Solution object for BVP
+
+        Raises:
+            NotImplementedError: BVP implementation arrives in Milestone 5
+        """
+        raise NotImplementedError("BVP in Milestone 5")
+
+
+def solve_bvp_scipy(equation, boundary_conditions, tspan, **kwargs):
+    """
+    Solve a BVP using SciPy's solve_bvp.
+
+    This is a placeholder for future implementation.
+    """
+    raise NotImplementedError(
+        "SciPy BVP backend will be implemented in later playbooks"
+    )

odecast/backends/scipy_ivp.py

@@ -0,0 +1,134 @@
+"""
+SciPy-based backend for solving initial value problems
+"""
+
+from typing import Dict, Tuple, Callable, Optional, Any, Union
+import numpy as np
+from scipy.integrate import solve_ivp
+
+from ..symbols import Variable, Derivative
+from ..solution import SolutionIVP
+
+
+class ScipyIVPBackend:
+    """
+    Backend for solving IVPs using SciPy's solve_ivp.
+    """
+
+    def solve(
+        self,
+        f_compiled: Callable,
+        jac_compiled: Optional[Callable],
+        x0: np.ndarray,
+        t0: float,
+        tspan: Tuple[float, float],
+        mapping: Dict[Union[Variable, Tuple[Variable, int]], Union[list, int]],
+        options: Optional[Dict[str, Any]] = None,
+    ) -> SolutionIVP:
+        """
+        Solve the IVP using SciPy's solve_ivp.
+
+        Args:
+            f_compiled: Compiled RHS function f(t, x) -> dx/dt
+            jac_compiled: Compiled Jacobian function (optional)
+            x0: Initial state vector
+            t0: Initial time
+            tspan: Tuple of (t_start, t_end)
+            mapping: State mapping from build_state_map
+            options: Additional solver options
+
+        Returns:
+            SolutionIVP object with results
+        """
+        options = options or {}
+
+        # Extract solver options
+        method = options.get("method", "RK45")
+        rtol = options.get("rtol", 1e-3)
+        atol = options.get("atol", 1e-6)
+        events = options.get("events", None)
+        dense_output = options.get("dense_output", False)
+        max_step = options.get("max_step", np.inf)
+
+        # Solve using scipy.integrate.solve_ivp
+        sol = solve_ivp(
+            fun=f_compiled,
+            t_span=tspan,
+            y0=x0,
+            method=method,
+            rtol=rtol,
+            atol=atol,
+            events=events,
+            dense_output=dense_output,
+            max_step=max_step,
+            jac=jac_compiled,
+        )
+
+        if not sol.success:
+            raise RuntimeError(f"SciPy solve_ivp failed: {sol.message}")
+
+        # Create and return SolutionIVP object
+        return SolutionIVP(
+            t=sol.t,
+            y=sol.y,
+            mapping=mapping,
+            t0=t0,
+            f_compiled=f_compiled,
+            jac_compiled=jac_compiled,
+            x0=x0,
+        )
+
+
+def convert_ivp_to_state_vector(
+    ivp_dict: Dict[Union[Variable, Derivative], float],
+    mapping: Dict[Union[Variable, Tuple[Variable, int]], Union[list, int]],
+) -> np.ndarray:
+    """
+    Convert IVP dictionary to initial state vector.
+
+    Args:
+        ivp_dict: Dictionary mapping variables/derivatives to initial values
+        mapping: State mapping from build_state_map
+
+    Returns:
+        Initial state vector x0
+    """
+    # Import here to avoid circular import
+    from ..validate import normalize_ivp
+
+    # Normalize the IVP dictionary to handle vector variables
+    normalized_ivp = normalize_ivp(ivp_dict)
+
+    # Determine the size of the state vector
+    max_index = 0
+    for key, value in mapping.items():
+        if isinstance(key, tuple):  # (var, level) keys
+            max_index = max(max_index, value)
+        elif isinstance(key, Variable):  # var keys with lists
+            if isinstance(value, list) and value:
+                max_index = max(max_index, max(value))
+
+    n_states = max_index + 1
+    x0 = np.zeros(n_states)
+
+    # Fill in the initial conditions using normalized format
+    for (var, level), value in normalized_ivp.items():
+        if (var, level) in mapping:
+            state_index = mapping[(var, level)]
+            x0[state_index] = value
+        # else: silently ignore conditions that aren't needed
+        # This happens when vector derivatives are provided but some
+        # components don't need that level of derivative
+
+    return x0
+
+
+def solve_ivp_scipy(equation, initial_conditions, tspan, **kwargs):
+    """
+    Solve an IVP using SciPy's solve_ivp.
+
+    This is a placeholder that will be removed once the ScipyIVPBackend is integrated.
+    """
+    raise NotImplementedError(
+        "SciPy IVP backend will be implemented in later playbooks"
+    )