[superwhiskers]

Description

prepares the solver and cli interfaces for co-simulation work

Proposed changes

there's a small amount of diff noise here from breaking this out of the earlier monolithic commit which included formatting changes. that can be reduced further if necessary

• add a nix development environment
• extend cli parsing to support positional arguments
• extend kinsol with callback-based solves
• improve sundials interface error handling and monitor control
• add fault support to signal voltage output buses
• support external signal bindings in jacobian tests

Checklist

• All tests pass.
• Code compiles cleanly with flags -Wall -Wpedantic -Wconversion -Wextra.
• The new code follows GridKit™ style guidelines.
• There are unit tests for the new code.
• The new code is documented.
• The feature branch is rebased with respect to the target branch.
• The CHANGELOG.md has been updated to reflect the changes. If this is a minor PR that is part of a larger fix already included in the file, state so.

[read-the-docs-community]

Documentation build overview

📚 GridKit | 🛠️ Build #35624035 | 📁 Comparing 866f332 against latest (9963c0d)

  🔍 Preview build  

72 files changed · + 23 added · ± 49 modified

+ Added

• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Controller_1a66f8c7d54bb07fa22c0624fbcad99e27.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Controller_1aefd1fdba25de1cd8776a2bba60e31038.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Converter_1a6ae59f9dcd6349e5d4eab9ce80b8325d.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Exciter_1a4b9e955f53e1d19553c5f7891f45e16d.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Exciter_1a628ca82ee36d28b56d83c736030da664.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Exciter_1a929ec4e288879a1988ee8338292907e7.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Governor_1a957ae037c7612dc470d576b77aacb912.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Governor_1acaf031464dd18f3e866eb694f42abf8a.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Governor_1ad7777e6d4c0695f9fdc8b7e2de291121.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Stabilizer_1a4308633e7f5c0612b5eb30aab54bb033.html
• and 13 more...

± Modified

• genindex.html
• development/CHANGELOG.html
• api/reference/classAnalysisManager_1_1Sundials_1_1Kinsol.html
• api/reference/classAnalysisManager_1_1Sundials_1_1SundialsException.html
• api/reference/classGridKit_1_1PhasorDynamics_1_1BusSignalVoltageOut.html
• api/reference/classGridKit_1_1Utilities_1_1CliArgs.html
• api/reference/dir_GridKit_Solver.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Converter_1a16b1d29ea875a07de79a63f17a47a9ff.html
• api/reference/enum_namespaceGridKit_1_1PhasorDynamics_1_1Converter_1a584b7e7f14739c0946c4b431ec262368.html
• api/reference/file_GridKit_AutomaticDifferentiation_DependencyTracking_VariableOperators.hpp.html
• and 39 more...

[lukelowry]

Some initial thoughts. Also, I don't know much about .nix, could you give some info? Looks like good architecture changes overall

[lukelowry]

Out of scope of PR, but why is this arbitrarily + 0.1? Could this be related to convergence issues post-fault? @Steven-Roberts

[Steven-Roberts]

The argument should be

the first value of 𝑡 at which a solution will be requested (from IDASolve()). This value is needed here only to determine the direction of integration and rough scale in the independent variable 𝑡.

Since we don't have access to tf yet, I guess + 0.1 was arbitrarily picked. The convergence issues typically occur a couple steps after IDACalcIC is called, we I don't think this is the culprit. Nevertheless, I can check and see if another value is more principled here.

[lukelowry]

This feels like an unfortunate place to add printMonitor, thoughts?

[superwhiskers]

Also, I don't know much about .nix, could you give some info?

this was only in here initially due to the patched enzyme to make using it easier for others. i've left it in here as it's a harmless change so i can stop maintaining the environment out of tree, but it can be removed if necessary. as it's used here, it's just a way of describing how to build gridkit / set up an environment for developing it. if you want more information than that / want to try to use it, you can learn more here.

if you have access to the excl cluster, a handful of the machines there have it

[nkoukpaizan]

Also, I don't know much about .nix, could you give some info?

this was only in here initially due to the patched enzyme to make using it easier for others. i've left it in here as it's a harmless change so i can stop maintaining the environment out of tree, but it can be removed if necessary. as it's used here, it's just a way of describing how to build gridkit / set up an environment for developing it. if you want more information than that / want to try to use it, you can learn more here.

if you have access to the excl cluster, a handful of the machines there have it

Perhaps move the relevant nix files to buildsystem/ and add some documentation, similar to what we have for Spack. Note that ExCL is not widely available outside of ORNL.

[superwhiskers]

Perhaps move the relevant nix files to buildsystem/

conventionally flake.nix is at the root of the repository, as then you can run nix develop at the root and be placed into a shell containing the software used to develop gridkit. i can remove the .envrc though as this was just to automatically load the dependencies into the shell environment without needing that extra step

additionally, if it weren't at the root, then someone wanting to pull in gridkit as an input to a flake of their own would need to override the directory it is in.

Note that ExCL is not widely available outside of ORNL.

and to clarify, you can use nix on any machine you want, i only mentioned excl as it's already installed on some of the machines there. if you don't have access or want to use it on a personal machine it's something you could freely install yourself as i have

[pelesh]

The proposed changes here need more discussion and a dedicated issue(s).

A few obvious suggestions:

• Buses wired to signals should not be faulted. Adding fault support for those is a distraction at this point.
• No changes to Ida should be made in this PR. Most of the changes to Ida as I see are formatting changes and these must be reverted before the review.
• If changes to Kinsol are required, they need to be discussed in a separate issue.
• All flake related configuration needs to be removed. We are using Spack for packaging, so any configuration adjustments should be contributed there.

[pelesh]

I suggest we make busses with associated signals "unfaultable". When you dedicate a bus as a co-simulation connection point, you typically don't want to fault it.

Suggested change

	virtual int setFault(bool status, RealT R, RealT X) override final;
	virtual int allocate() override final;
	virtual int allocate() override final;

[pelesh]

Similarly, remove fault support for signal connected buses elsewhere in the code.