DAE initialization note #604

termi-official · 2023-02-24T15:38:59Z

Trying to address #603 .

KnutAM · 2023-02-24T19:06:05Z

docs/src/manual/initial_and_boundary_conditions.md

+!!! note "Initialization of Differential-Algebraic Systems"
+    Differential-algebraic systems of equations (DAEs) need extra care during initialization, which is 
+    currently not automatized by the function `apply_analytical!`.
+    Skipping the formal definition, you can identify DAEs for example by 
+    * Multiple time derivatives in the equation
+    * The equations cannot be formulated such that the variable with the time-derivative 
+      is the only term on the right hand side
+    * Missing time derivatives
+    To give concrete example of a "DAE" (formally a PDAE, which becomes a DAE by spatial discretization), consider following
+    abstract problem on some domain with ``u(t,\boldsymbol{x})`` and ``s(t,\boldsymbol{x})`` being the unknown variables:
+    ```math
+        \partial_t u(t,\boldsymbol{x})) = f(u(t,\boldsymbol{x}), \nabla u(t,\boldsymbol{x}), s(t,\boldsymbol{x})) \\
+        0 = g(u(t,\boldsymbol{x}), \nabla u(t,\boldsymbol{x}), s(t,\boldsymbol{x}))
+    ```
+    Here ``s`` might be some internal state variable, e.g. describing hardening, failure or some electrical
+    state and ``u`` could be a displacement field or some potential field. This form is quite common in mechanics,
+    for example in quasi-static analysis of plastic materials.
+    For DAEs need to assert that the hidden constraints of the problem are not violated by the choice
+    of initial conditions.
+    What the exact hidden constraints are have to be worked out on the specific DAE.
+    For the example above it is sometimes possible to just solve the second equation for ``s``, i.e.
+    ```math
+    0 = g(u(t,\boldsymbol{x}), \nabla u(t,\boldsymbol{x}), s(t,\boldsymbol{x}))
+    ```
+    given some fixed choice of ``u``.
+    We refer to the paper ["Consistent Initial Condition Calculation for Differential-Algebraic Systems" 
+    by Brown et al.](dx.doi.org/10.1137/S1064827595289996) for more details on this matter and some possible solutions.
+


Thanks for providing such a detailed description Dennis, it is very interesting!
But this does indeed seem very difficult to explain in simple terms for the general case to not confuse (new) users.
Thinking more about this, could something like the following, even if over-simplistic, work?

Suggested change

!!! note "Initialization of Differential-Algebraic Systems"

Differential-algebraic systems of equations (DAEs) need extra care during initialization, which is

currently not automatized by the function `apply_analytical!`.

Skipping the formal definition, you can identify DAEs for example by

* Multiple time derivatives in the equation

* The equations cannot be formulated such that the variable with the time-derivative

is the only term on the right hand side

* Missing time derivatives

To give concrete example of a "DAE" (formally a PDAE, which becomes a DAE by spatial discretization), consider following

abstract problem on some domain with ``u(t,\boldsymbol{x})`` and ``s(t,\boldsymbol{x})`` being the unknown variables:

```math

\partial_t u(t,\boldsymbol{x})) = f(u(t,\boldsymbol{x}), \nabla u(t,\boldsymbol{x}), s(t,\boldsymbol{x})) \\

0 = g(u(t,\boldsymbol{x}), \nabla u(t,\boldsymbol{x}), s(t,\boldsymbol{x}))

```

Here ``s`` might be some internal state variable, e.g. describing hardening, failure or some electrical

state and ``u`` could be a displacement field or some potential field. This form is quite common in mechanics,

for example in quasi-static analysis of plastic materials.

For DAEs need to assert that the hidden constraints of the problem are not violated by the choice

of initial conditions.

What the exact hidden constraints are have to be worked out on the specific DAE.

For the example above it is sometimes possible to just solve the second equation for ``s``, i.e.

```math

0 = g(u(t,\boldsymbol{x}), \nabla u(t,\boldsymbol{x}), s(t,\boldsymbol{x}))

```

given some fixed choice of ``u``.

We refer to the paper ["Consistent Initial Condition Calculation for Differential-Algebraic Systems"

by Brown et al.](dx.doi.org/10.1137/S1064827595289996) for more details on this matter and some possible solutions.

!!! note "Initialization of Differential-Algebraic Systems"

Note that `apply_analytical!` does not ensure consistency between the applied field

and the specific problem being solved. As a simple example, consider a mechanical problem:

`apply_analytical!` doesn't ensure that equilibrium is fulfilled in the initial state.

In general for advanced, so-called "Differential-Algebraic Systems",

consistent initialization is a research field on its own, see e.g.

["Consistent Initial Condition Calculation for Differential-Algebraic Systems" by Brown et al.](dx.doi.org/10.1137/S1064827595289996)

or do you think this misses the point since in many cases a non-equilibrium initial condition is perfectly fine (and we even demo that in the transient heat flow:))

I am, however, sad not to have all such knowledge/insights available. From that perspective, it might have been nice to have a separate webpage containing "Ferrite: Theory and examples" (or something) to supplement the documentation, but that's a different discussion

Thanks for looking into this and the suggestion. I am happy and open for ideas on how to improve/simplify this part. However, the point here is not about equilibrium, but about consistency of the solution. This is especially problematic in differential-algebraic problems.

Think about it this way: The algebraic equations act as constraints on the time evolution of your problem, where the constraints also have some "implicit" or "hidden evolution". However, the constraint might not be directly visible in the equation and hence messing it up can be very easy (for example if a zero initialization of some internal variable could be inconsistent with your evolving field variable).

Don't you think the (theory) manual we have is sufficient in combination with the examples?

Yes, I agree that equilibrium is not the point. I meant it more as a warning that one can not supply whatever initial condition but have to ensure that it is consistent with the problem to be solved.

(The additional site was more a long term idea that would be useful for e.g. teaching and reference since you, we and maybe more use Ferrite in teaching, for which I think the current state is not meant to be, nor detailed enough, as course material)

KnutAM · 2023-02-24T19:07:36Z

docs/src/manual/initial_and_boundary_conditions.md

+    given some fixed choice of ``u``.
+    We refer to the paper ["Consistent Initial Condition Calculation for Differential-Algebraic Systems" 
+    by Brown et al.](dx.doi.org/10.1137/S1064827595289996) for more details on this matter and some possible solutions.
+
 See also [Time Dependent Problems](@ref) for one example.


Should we put this above the note?

Quick question here, why would you move it above the note?

It is easy to miss that reference when reading the docs, but if switched, the note is still hard to miss. And it follows (in my mind) more logically as DAEs are not discussed in that example.

KnutAM

But I like the new commit!
If the example link is moved above the note, I think it good to go!

codecov-commenter · 2023-02-24T20:23:04Z

Codecov Report

Patch and project coverage have no change.

Comparison is base (8c32dd1) 93.05% compared to head (c4c5d60) 93.05%.

❗ Current head c4c5d60 differs from pull request most recent head cc1a162. Consider uploading reports for the commit cc1a162 to get more accurate results

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #604   +/-   ##
=======================================
  Coverage   93.05%   93.05%           
=======================================
  Files          28       28           
  Lines        4277     4277           
=======================================
  Hits         3980     3980           
  Misses        297      297

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

docs/src/manual/initial_and_boundary_conditions.md

Co-authored-by: Knut Andreas Meyer <knutam@gmail.com>

fredrikekre

I suggest keeping the filename (which translates to the URL) even though the header changes so that old links will still work.

docs/make.jl

docs/src/reference/initial_and_boundary_conditions.md

fredrikekre · 2023-02-28T13:27:52Z

Forgot to actually rename the file back :D

fredrikekre · 2023-02-28T14:55:47Z

docs/src/manual/initial_and_boundary_conditions.md

+!!! note "Consistency"
+    `apply_analytical!` does not enforce consistency of the applied solution with the system of 
+    equations. Some problems, like for example differential-algebraic systems of equations (DAEs)
+    need extra care during initialization. We refer to the paper ["Consistent Initial Condition Calculation for Differential-Algebraic Systems"  by Brown et al.](dx.doi.org/10.1137/S1064827595289996) for more details on this matter.


Probably you should use the full https URL instead, this gives:

┌ Warning: invalid local link: unresolved path in manual/boundary_conditions.md │ link_url = "dx.doi.org/10.1137/S1064827595289996" └ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/ZRco4/src/html/HTMLWriter.jl:2195

Dennis Ogiermann added 2 commits February 24, 2023 15:17

Rename file.

aa17e78

Trying to explainthat DAE initialization can be quite problematic.

f7318c5

termi-official requested a review from KnutAM February 24, 2023 15:39

KnutAM reviewed Feb 24, 2023

View reviewed changes

Try to condense the information and kick out the example.

4aa837a

KnutAM approved these changes Feb 24, 2023

View reviewed changes

Move DAE initialization link above note.

09a2c79

KnutAM reviewed Feb 25, 2023

View reviewed changes

docs/src/manual/initial_and_boundary_conditions.md Outdated Show resolved Hide resolved

Update docs/src/manual/initial_and_boundary_conditions.md

c4c5d60

Co-authored-by: Knut Andreas Meyer <knutam@gmail.com>

fredrikekre reviewed Feb 28, 2023

View reviewed changes

docs/make.jl Outdated Show resolved Hide resolved

docs/make.jl Outdated Show resolved Hide resolved

docs/src/reference/initial_and_boundary_conditions.md Outdated Show resolved Hide resolved

Apply suggestions from code review

cc1a162

fredrikekre merged commit 13a0739 into master Feb 28, 2023

fredrikekre deleted the do/dae-init-docs branch February 28, 2023 13:05

fredrikekre added a commit that referenced this pull request Feb 28, 2023

git mv files back, fixup from #604.

ac098f0

fredrikekre reviewed Feb 28, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DAE initialization note #604

DAE initialization note #604

termi-official commented Feb 24, 2023

KnutAM Feb 24, 2023

termi-official Feb 24, 2023

KnutAM Feb 24, 2023

KnutAM Feb 24, 2023

termi-official Feb 24, 2023

KnutAM Feb 24, 2023

KnutAM left a comment

codecov-commenter commented Feb 24, 2023 •

edited

Loading

fredrikekre left a comment

fredrikekre commented Feb 28, 2023

fredrikekre Feb 28, 2023

DAE initialization note #604

DAE initialization note #604

Conversation

termi-official commented Feb 24, 2023

KnutAM Feb 24, 2023

Choose a reason for hiding this comment

termi-official Feb 24, 2023

Choose a reason for hiding this comment

KnutAM Feb 24, 2023

Choose a reason for hiding this comment

KnutAM Feb 24, 2023

Choose a reason for hiding this comment

termi-official Feb 24, 2023

Choose a reason for hiding this comment

KnutAM Feb 24, 2023

Choose a reason for hiding this comment

KnutAM left a comment

Choose a reason for hiding this comment

codecov-commenter commented Feb 24, 2023 • edited Loading

Codecov Report

fredrikekre left a comment

Choose a reason for hiding this comment

fredrikekre commented Feb 28, 2023

fredrikekre Feb 28, 2023

Choose a reason for hiding this comment

codecov-commenter commented Feb 24, 2023 •

edited

Loading