ORNL / ORNL/GridKit

Documentation improvements for EMT & PhasorDynamics

Open
#532 1 comment 0 reactions 2 assignees View on GitHub

@lukelowry is already working on this.

Since Aug 10, 2026.

documentation
Dominant language
C++
Stars
27
Forks
11
Avg merge
3d 8h
Merged PRs (30d)
23

Description

Summary

These are some remarks I have for making the docs more clear.
I will update this on a rolling basis (I'm partway through the docs).

  • 1. I see the index for devices is $e$, which looks the same as Euler's constant, which you also use. This is unlikely to create confusion because context will likely determine which is correct, but it's still better to have something else. You could also just use exp$(x)$ instead of $e^x$. $e$ also appears as a voltage vector.
  • 2. Here and elsewhere, it seems that the variables have the same non-indexed JSON name. Why is that?
  • 3. Remove the comment here about partially singular coefficients. You can say "nonzero yet singular coefficients" if you want to keep it.
  • 4. Unclear sentence
  • I think these conditions are required (as opposed to required to not hold), but your sentence as ambiguous. How about something like:
    "Branch parameter are required to meet these criteria:
    ...,
    Otherwise, they are rejected.
    "
  • 5. Similar to 4 see here. Which conditions listed above? I thought those were the conditions you want to hold.
  • 6. Extra $s
  • 7. Legend's parameters not formatted
  • 8. See 4.. Confusing and redundant with next section, remove "the time-constant floor below is then applied."
  • 9. REPCA - see comments for REECB
  • 10. It may be useful to link to the CommonMath function directly (assuming this is doable) when citing it.
  • 11. So these are inverses of the smoothed functions? That's ambiguous (though logically mathematically, the piecewise function has no inverse).
  • 12. In multiple cases it seems that if you set limits and don't meet them, the code just ignores it and expands the limits (throwing a warning). Why is this desirable? I think an error would be better.
  • 13. See 4 and reword every instance of the text after "Parameter Validation"
  • 14. Poweworld -> Powerworld
  • 15. Second block the placement of $V_B$ is weird because no parenthesis are needed. (Unless there is some other typo)
  • 16. What is a negative minimum error? error is always nonnegative as far as I know.
  • 17. Equation error here

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.