Initial Implementation of Subsystem Model for Partition Simulation

[abdourahmanbarry]

Description

In this PR, we introduce the initial implementation of the SubsystemModel for partitioned Power Electronics simulation. The implementation provides the infrastructure required to partition Power Electronic networks, and to evaluate subsystem residuals and Jacobians independently. This lays the foundation for implementing co-simulation methods in future pull requests.

Proposed changes

• We added a SubsystemModel class to represent an individual partition and a BusPartitionInterface component to mark partition boundaries.
• Implemented residual and Jacobian evaluation for subsystem models.
• Added support for user-defined coupling functions required for solving subsystems with multi-stage co-simulation methods.

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.
• I have updated CHANGELOG.md to reflect the changes in this PR. If this is a minor PR that is part of a larger fix already included in the file, state so.

[abdourahmanbarry]

This pull request is ready for review.

[alexander-novo]

Suggested change

	void setTimeFunction(TimeFunction function)
	{
	forcing_function_ = std::move(function);
	}
	void setTimeFunction(TimeFunction&& function)
	{
	forcing_function_ = std::move(function);
	}

Good to use an r-value reference if you're going to use std::move. But also this may be unnecesary.

[nkoukpaizan]

I few initial comments on the Hires example. I'll take a closer look at the partition interface after comments by @alexander-novo have been addressed.

[nkoukpaizan]

I recommend further documenting what Hires Bus is in this file. I'm surprised there's a need for a derived component class in the examples directory. Consider moving to tests and encapsulating the necessary components.

[abdourahmanbarry]

I will add a README file to document this example further. It was meant as a simple example to demonstrate the partitioning scheme due the simplicity of the equations involved. I will use it late for order testing of the co-simulation methods. If it is preferred in the tests folder, I can move it there as well.

[nkoukpaizan]

Are we not expecting machine precision accuracy?

[abdourahmanbarry]

Due to the non-associativity of floating point arithmetic, the the difference between the entries in the subsystem and monolithic Jacobian may be little bit higher than machine precision when the order of evaluation of the components are different between the reference and subsystem. In this case though we should expect exact match since the components are evaluated in the same order in both the monolithic and subsystems. I will tighten the tolerance here.

[alexander-novo]

Couple of comments on this:

1. The final result is only guaranteed to be within machine precision if a single floating point operation is being done. But since there are potentially multiple sum operations being taken which may be reordered, this can't be guaranteed.
2. The tolerance is being applied to an absolute error, and not a relative error. So the error may be larger than machine precision of the expected Jacobian values are larger than 1.

[nkoukpaizan]

My point was that I would expect I tighter tolerance than 1e-12 and I don't find an absolute error helpful in this context. The modified relative error in GridKit::Testing::isEqual() should help with normalization.

[abdourahmanbarry]

In my experience, the non-associativity of floating-point addition can sometimes lead to surprisingly large differences. This is just one example from MATLAB:

>> a = 20.7448;
>> b = -16.0002;
>> c = 130001;
>> d = -130003;
>> 
>> p = a + b + c + d;
>> q = a + c + d + b;
>> 
>> abs(p - q)/abs(q)

ans =

     1.840690392499302e-12

>> 

In cpp:

  double a = 20.7448;
  double b = -16.0002;
  double c = 130001.0;
  double d = -130003.0;

  double p = a + b + c + d;
  double q = a + c + d + b;
  std::cout << "Matched: " << GridKit::Testing::isEqual(p, q, 1e-12) << std::endl;

output:
Matched: 0 // false

[nkoukpaizan]

This is well understood behavior. For the example you show, we would want to explicitly mitigate the error by normalizing or by using parentheses. Good algorithms and implementations are designed with this in mind, knowing expected inputs and coefficients. We'd want to catch this kind of thing early in tests. I recommend adding a comment if satisfying a tighter tolerance is not expected.