ODEModel

Overview

The ODEModel class provides a concrete implementation of an ODE system model, allowing users to define, manipulate, and evaluate systems of ordinary differential equations (ODEs). It extends the abstract base class ODEModelBase to enforce a consistent interface and structure.

This documentation explains the purpose and usage of the ODEModel class, including examples and details of its methods and attributes.

---

Table of Contents

1. Abstract Base Class: ODEModelBase
2. Concrete Class: ODEModel
   • Attributes
   • Constructors
   • Methods
3. Examples
4. Purpose of the Abstract Base Class

---

Abstract Base Class: ODEModelBase

The ODEModelBase serves as a blueprint for ODE models, ensuring any concrete implementation provides the following methods:

class ODEModelBase(ABC):
    """
    Abstract base class to define the structure and types for an ODE model.
    """

    def __init__(self):
        # Define properties with specific types
        self.equations: List[Expr] = []  # List of equation expressions
        self.functions: List[Callable] = []  # List of equation functions
        self.variables: List[str] = []   # List of variable names
        self.parameters: Dict[str, float] = {}  # Dictionary of parameter names and values
        self.constraints: List[Constraint] = []  # List of constraint objects (Eq, Lt, Gt, Le, Ge)
        self.initial_conditions: Dict[str, float] = {} # Dictionary of initial conditions names and values

    @abstractmethod
    def set_equations(self, equations) -> None:
        """
        Abstract method to set the equations for the model.
        """
        pass

    @abstractmethod
    def set_variables(self, variables) -> None:
        """
        Abstract method to set the variables for the model.
        """
        pass

    @abstractmethod
    def set_parameters(self, parameters) -> None:
        """
        Abstract method to set the parameters for the model.
        """
        pass

    @abstractmethod
    def set_constraints(self, constraints) -> None:
        """
        Abstract method to set the constraints for the model.
        """
        pass

    @abstractmethod
    def set_initial_conditions(self, constraints) -> None:
        """
        Abstract method to set the constraints for the model.
        """
        pass

    @abstractmethod
    def evaluate(self, y: List[float]) -> List[float]:
        """
        Abstract method to evaluate the system of ODEs at a given point.
        """
        pass

    def integrate_system(self, independent_values: List[float]):
        """
        Integrates the system of ODEs.
        """
        pass

---

Concrete Class: ODEModel

Attributes

• equations: List of sympy.Expr objects representing the ODE system.
• variables: List of strings representing the dependent variables.
• parameters: Dictionary of parameter names and their numeric values.
• constraints: List of sympy constraints (Eq, Lt, Gt, Le, Ge).
• initial_conditions: Dictionary mapping variables to their initial values.

Constructors

__init__

Initializes the model with equations, variables, parameters, constraints, and initial conditions.

Parameters:

• equations: List of strings representing the ODE equations.
• variables: List of variable names as strings.
• parameters: Dictionary of parameter names and their values.
• initial_conditions: Initial conditions as strings or a dictionary.
• constraints (optional): List of constraints as strings.

Example:

model = ODEModel(
    equations=["-k * x", "k * x - r * y"],
    variables=["x", "y"],
    parameters={"k": 0.1, "r": 0.05},
    constraints=["k > 0", "r > 0"],
    initial_conditions={"x": 1.0, "y": 0.0}
)

from_json

Loads an ODE model from a JSON file.

Example:

model = ODEModel.from_json("path/to/model.json")

from_yaml

Loads an ODE model from a YAML file.

Example:

model = ODEModel.from_yaml("path/to/model.yaml")

from_dict

Loads an ODE model from a dictionary.

Example:

model_data = {
    "equations": ["-k * x"],
    "variables": ["x"],
    "parameters": {"k": 0.1},
    "constraints": ["k > 0"]
    "initial_conditions"= {"x": 1.0}
}
model = ODEModel.from_dict(model_data)

Methods

evaluate

Evaluates the ODE system at a given point.

Parameters:

• y: List of values for the dependent variables.

Returns:

• List of evaluated derivatives.

Example:

values = [1.0, 0.5]
derivatives = model.evaluate(values)

graph

Plots the solution of the ODE system.

Parameters:

• independent_var: Array-like object for the independent variable.
• dependent_vars: List of array-like objects for the dependent variables.
• Other optional parameters for customization.

Example:

model.graph(time, [x_values, y_values], title="ODE Solution")

integrate_system

Integrates the system of ODEs using the odeint method from scipy.integrate. It returns the integration result.

Parameters:

• independent_var: Array-like object for the independent variable.

Example:

solution = ode_model.integrate_system(time_points)

Purpose of the Abstract Base Class

The ODEModelBase ensures any concrete implementation of an ODE model provides a consistent API. This is particularly useful for:

1. Code Reusability: Enforcing a standard interface across multiple ODE model implementations.
2. Flexibility: Allowing different concrete classes to extend the base class and add specific features.
3. Error Prevention: Ensuring that essential methods are implemented, reducing the risk of runtime errors.