DAE doc

[yizhang-yiz]

Submission Checklist

• Builds locally
• New functions marked with `r since("VERSION")`
• Declare copyright holder and open-source license: see below

Summary

For stanc3 issue 1091.

Copyright and Licensing

Please list the copyright holder for the work you are submitting (this will be you or your assignee, such as a university or company):

Metrum Research Group

By submitting this pull request, the copyright holder is agreeing to license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
• Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

[yizhang-yiz]

@charlesm93 perhaps this PR can of help for the math PR review.

[yizhang-yiz]

Per @charlesm93 's review comment stan-dev/math#2644 (comment) I just added a section on DAE index.

[yizhang-yiz]

Now that stan-dev/math#2644 is in, @charlesm93 do you have time to review its doc? Thanks.

[charlesm93]

Sure.

[WardBrian]

Some typos and suggestions in the functions reference (not familiar enough with the math for the users guide sections)

[charlesm93]

Overall this looks good. I'm requesting a few minor changes, see the comments on the code. Additionally, the first paragraph (under Differential-Algebraic equation (DAE) solver) should include a brief statement about how DAEs defer from the ODEs and algebraic equations.

[charlesm93]

I see my comments have been addressed. I still recommend a brief sentence on how DAEs differ from ODEs (and algebraic equations) at the beginning. It might also be worth pointing out that we can solve a broader class of ODEs using the DAE solver, i.e. one where the residual equation is non-linear in y'. Once this is in place, we can merge the PR.

[yizhang-yiz]

I see my comments have been addressed. I still recommend a brief sentence on how DAEs differ from ODEs (and algebraic equations) at the beginning. It might also be worth pointing out that we can solve a broader class of ODEs using the DAE solver, i.e. one where the residual equation is non-linear in y'. Once this is in place, we can merge the PR.

@charlesm93 I added

One can think a differential-algebraic system of equations
as ODEs with additional algebraic constraits applied to some
of the variables. In such a system, the variable derivatives may not be
expressed explicitly with a right-hand-side as in ODEs, but implicitly
constrained.

[charlesm93]

I don't think this quite gets to it. The phrasing suggests the algebraic constraints apply only to variables in the "original ODE" and the term RHS here is ambiguous, since it may refer to a quantity equal to the derivative or to 0. Here's an attempt at rephrasing this:

The solution to a differential-algebraic equation must simultaneously verify a system of ODEs and a system of algebraic equations. In this sense, DAEs generalize ODEs and algebraic equations. Solution states may appear in both the differential and algebraic systems, or in only one of the systems. If a variable only appears in the algebraic system, it derivative is not explicitly, rather implicitly, constrained.

[yizhang-yiz]

The solution to a differential-algebraic equation must simultaneously verify a system of ODEs and a system of algebraic equations.

technically this is not true, as in a DAE there may not be a ODEs system. What you are referring is semi-explicit DAEs.

[yizhang-yiz]

@charlesm93 I'm having trouble to come up with " a brief sentence on how DAEs differ from ODEs ". Neither mine or yours are sufficiently simple without being misleading. I think the user who's using the feature has to be familiar with DAEs. After all we don't introduce what ODEs are at the ODE section.

However, if we must, the simple sentence from wikipedia is the best I can think of:

a differential-algebraic system of equations (DAEs) is a system of equations that either contains differential equations and algebraic equations, or is equivalent to such a system.

We can use this if you're ok.

[charlesm93]

I think you're right that the user we'll know what a DAE is if they're interested in using this feature. Best not to write a misleading statement. With that, you can go ahead a merge the PR.