diff --git a/docs/src/API/variables.md b/docs/src/API/variables.md index 6f48c9a5f8..b39fc8499d 100644 --- a/docs/src/API/variables.md +++ b/docs/src/API/variables.md @@ -337,6 +337,7 @@ ModelingToolkit also defines a plethora of custom operators. Pre Initial Shift +EvalAt ``` While not an operator, `ShiftIndex` is commonly used to use `Shift` operators in a more diff --git a/src/variables.jl b/src/variables.jl index a4f0b5532f..b61298eca2 100644 --- a/src/variables.jl +++ b/src/variables.jl @@ -578,6 +578,59 @@ getshift(x::Symbolic) = Symbolics.getmetadata(x, VariableShift, 0) ################### ### Evaluate at ### ################### +""" + EvalAt(t) + +An operator that evaluates time-dependent variables at a specific absolute time point `t`. + +# Fields +- `t::Union{Symbolic, Number}`: The absolute time at which to evaluate the variable. + +# Description +`EvalAt` is used to evaluate time-dependent variables at a specific time point. This is particularly +useful in optimization problems where you need to specify constraints or costs at particular moments +in time, or delay differential equations for setting a delay time. + +The operator works by replacing the time argument of time-dependent variables with the specified +time `t`. For variables that don't depend on time, `EvalAt` returns them unchanged. + +# Behavior +- For time-dependent variables like `x(t)`, `EvalAt(τ)(x)` returns `x(τ)` +- For time-independent parameters, `EvalAt` returns them unchanged +- For derivatives, `EvalAt` evaluates the derivative at the specified time +- For arrays of variables, `EvalAt` is applied element-wise + + +# Examples +```julia +using ModelingToolkit + +@variables t x(t) y(t) +@parameters p + +# Evaluate x at time t=1.0 +EvalAt(1.0)(x) # Returns x(1.0) + +# Works with parameters (returns unchanged) +EvalAt(1.0)(p) # Returns p + +# Works with derivatives +D = Differential(t) +EvalAt(1.0)(D(x)) # Returns D(x) evaluated at t=1.0 + +# Use in optimization constraints +@optimization_model model begin + @constraints begin + EvalAt(0.5)(x) ~ 2.0 # x must equal 2.0 at t=0.5 + end +end +``` + +# Errors +- Throws an error when applied to variables with more than one argument (e.g., `z(u, t)`) + +See also: [`Differential`](@ref) +""" struct EvalAt <: Symbolics.Operator t::Union{Symbolic, Number} end