Skip to content

Add comprehensive documentation for array variables (fixes #956) #3839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 1 commit into from
Closed

Add comprehensive documentation for array variables (fixes #956) #3839

wants to merge 1 commit into from

Conversation

ChrisRackauckas
Copy link
Member

Summary

This PR adds comprehensive documentation for array (vector) variables in ModelingToolkit, addressing the long-standing issue #956 from February 2024.

Problem

Users were struggling to discover how to create symbolic vectors/arrays in ModelingToolkit. The syntax @variables x[1:n](t) was not documented in MTK's documentation, only in Symbolics.jl docstrings. Additionally, users who tried to pass vector initial conditions to scalar variables received confusing error messages.

Solution

Added a comprehensive tutorial "Working with Array Variables" that covers:

📚 Tutorial Contents

  1. Basic Syntax

    • Clear examples of @variables x[1:3](t) creating x[1](t), x[2](t), x[3](t)
    • Array parameters: @parameters k[1:3]

  2. Practical Examples

    • Complete mass-spring system with 3 masses
    • Shows equation building with loops
    • Demonstrates initial conditions and parameter assignment

  3. Advanced Topics

    • Multi-dimensional arrays
    • Array comprehensions for concise equation definition
    • Setting default values for arrays
    • Variable-sized arrays using @mtkmodel

  4. Troubleshooting

📝 Additional Changes

  • Added tutorial to documentation navigation
  • Updated ode_modeling.md to mention array variables
  • Removed outdated "work in progress" text about vector variables

Example from the Tutorial

# Create array variables
@variables x[1:3](t) v[1:3](t)
@parameters k[1:3] m[1:3]

# Build equations programmatically
eqs = [D(x[i]) ~ v[i] for i in 1:3]

Testing

The tutorial includes complete, runnable examples that demonstrate:

  • Creating and solving ODE systems with array variables
  • Proper initial condition syntax
  • Plotting results

Closes #956

🤖 Generated with Claude Code

@ChrisRackauckas @claude
Add comprehensive documentation for array variables (fixes #956)
3d745d1 
This commit adds clear documentation for creating and using array (vector)
variables in ModelingToolkit, addressing the long-standing issue #956.

Changes:
- Added new tutorial "Working with Array Variables" covering:
  - Basic array variable syntax `@variables x[1:n](t)`
  - Array parameters
  - Building systems with array variables (mass-spring example)
  - Initial conditions and parameter values for arrays
  - Multi-dimensional arrays
  - Common patterns and tips (comprehensions, defaults, variable-sized)
  - Troubleshooting section addressing the specific error from issue #956
- Added the new tutorial to the documentation navigation in pages.jl
- Updated ode_modeling.md to:
  - Add a brief section introducing array variables
  - Update outdated text saying vector variables are "work in progress"
  - Link to the comprehensive array variables tutorial

The documentation now clearly explains the syntax that was previously only
documented in Symbolics.jl docstrings, and provides practical examples to
help users avoid common pitfalls like passing vector initial conditions to
scalar variables.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
baggepinnen
baggepinnen reviewed Jul 23, 2025
View reviewed changes
docs/src/tutorials/array_variables.md
# Define the system
n = 3 # number of masses

@variables x[1:n](t) v[1:n](t)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this gives warnings about deprecated syntax

github-actions[bot]
github-actions bot reviewed Jul 23, 2025
View reviewed changes
docs/src/tutorials/array_variables.md
push!(eqs, m[1] * D(v[1]) ~ -k[1] * x[1] + k[2] * (x[2] - x[1]) - c[1] * v[1])

# Middle masses
for i in 2:(n-1)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
for i in 2:(n-1)
for i in 2:(n - 1)

docs/src/tutorials/array_variables.md
# Middle masses
for i in 2:(n-1)
push!(eqs, D(x[i]) ~ v[i])
push!(eqs, m[i] * D(v[i]) ~ k[i] * (x[i-1] - x[i]) + k[i+1] * (x[i+1] - x[i]) - c[i] * v[i])
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
push!(eqs, m[i] * D(v[i]) ~ k[i] * (x[i-1] - x[i]) + k[i+1] * (x[i+1] - x[i]) - c[i] * v[i])
push!(eqs,
m[i] * D(v[i]) ~
k[i] * (x[i - 1] - x[i]) + k[i + 1] * (x[i + 1] - x[i]) - c[i] * v[i])

docs/src/tutorials/array_variables.md

# Last mass
push!(eqs, D(x[n]) ~ v[n])
push!(eqs, m[n] * D(v[n]) ~ k[n] * (x[n-1] - x[n]) - c[n] * v[n])
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
push!(eqs, m[n] * D(v[n]) ~ k[n] * (x[n-1] - x[n]) - c[n] * v[n])
push!(eqs, m[n] * D(v[n]) ~ k[n] * (x[n - 1] - x[n]) - c[n] * v[n])

docs/src/tutorials/array_variables.md

# Plot the solution
using Plots
plot(sol, idxs=[x[1], x[2], x[3]], labels=["x₁" "x₂" "x₃"])
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
plot(sol, idxs=[x[1], x[2], x[3]], labels=["x₁" "x₂" "x₃"])
plot(sol, idxs = [x[1], x[2], x[3]], labels = ["x₁" "x₂" "x₃"])

docs/src/tutorials/array_variables.md
Comment on lines +182 to +183
1. Use array variables: `@variables x[1:2](t)`
2. Provide scalar initial conditions: `[x => 1.0]`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
1. Use array variables: `@variables x[1:2](t)`
2. Provide scalar initial conditions: `[x => 1.0]`
1. Use array variables: `@variables x[1:2](t)`
2. Provide scalar initial conditions: `[x => 1.0]`

docs/src/tutorials/array_variables.md
Comment on lines +188 to +190
- Static arrays (`@SVector`, `@SMatrix`) for small, fixed-size arrays
- Sparse arrays for systems with sparse connectivity
- Symbolic simplification with `mtkcompile` to eliminate redundant calculations
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
- Static arrays (`@SVector`, `@SMatrix`) for small, fixed-size arrays
- Sparse arrays for systems with sparse connectivity
- Symbolic simplification with `mtkcompile` to eliminate redundant calculations
- Static arrays (`@SVector`, `@SMatrix`) for small, fixed-size arrays
- Sparse arrays for systems with sparse connectivity
- Symbolic simplification with `mtkcompile` to eliminate redundant calculations

docs/src/tutorials/array_variables.md
Comment on lines +196 to +201
- Use `@variables x[1:n](t)` syntax to create array variables
- Access elements with standard Julia indexing: `x[i]`
- Provide initial conditions and parameters for each array element
- Use array comprehensions for concise equation definition
- Multi-dimensional arrays are supported
- For variable-sized arrays, use `@mtkmodel` with structural parameters
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
- Use `@variables x[1:n](t)` syntax to create array variables
- Access elements with standard Julia indexing: `x[i]`
- Provide initial conditions and parameters for each array element
- Use array comprehensions for concise equation definition
- Multi-dimensional arrays are supported
- For variable-sized arrays, use `@mtkmodel` with structural parameters
- Use `@variables x[1:n](t)` syntax to create array variables
- Access elements with standard Julia indexing: `x[i]`
- Provide initial conditions and parameters for each array element
- Use array comprehensions for concise equation definition
- Multi-dimensional arrays are supported
- For variable-sized arrays, use `@mtkmodel` with structural parameters

docs/src/tutorials/ode_modeling.md
- Vector-valued parameters and variables are possible. A cleaner, more
consistent treatment of these is still a work in progress, however. Once finished,
this introductory tutorial will also cover this feature.
- Vector-valued parameters and variables are supported using array syntax like
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JuliaFormatter] reported by reviewdog 🐶

Suggested change
- Vector-valued parameters and variables are supported using array syntax like
- Vector-valued parameters and variables are supported using array syntax like

@ChrisRackauckas ChrisRackauckas deleted the docs-vector-variables-issue-956 branch July 23, 2025 13:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@baggepinnen baggepinnen baggepinnen left review comments

@github-actions github-actions[bot] github-actions[bot] left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Creating variables that are vectors of symbolic variables is not documented
2 participants
@ChrisRackauckas @baggepinnen