Declarative interface

[LasseNT]

A more declarative interface to writing models are being developed.

The aim is to have:

• clearer models with less boilerplate
• use declarations to allow static analysis of the models
• Allow better debugging information during model development

[mrdobalina2k]

It's unclear from the description what level of functionality is affected: is this a breaking change, a fix, or a new feature? It is important when prioritizing the review process, so please add some additional description. Perhaps we should create a pull request template @artem-chupryna to standardize this?

@LasseNT:
Please create an example that can be followed, and fix the tests/linters that are failing. The example can at a later stage (post merging) be placed in an example gallery together with the other examples of use cases.

[LasseNT]

It's unclear from the description what level of functionality is affected: is this a breaking change, a fix, or a new feature? It is important when prioritizing the review process, so please add some additional description. Perhaps we should create a pull request template @artem-chupryna to standardize this?

@LasseNT: Please create an example that can be followed, and fix the tests/linters that are failing. The example can at a later stage (post merging) be placed in an example gallery together with the other examples of use cases.
Hey @mrdobalina2k. Checks are passing now and I have added an example as per last commit. Please have a look and let me know if ok.

[mrdobalina2k]

Thanks @LasseNT. I looked at the example and here're my comments.

[mrdobalina2k]

What is this >> operator?

[LasseNT]

The >> or << operators are used as a short hand for connecting items.oscillator1.couplin with items.coupling.side1. Alternatives could be:
items.oscillator1.coupling.connect(items.coupling.side1)
connect(items.oscillator1.coupling, items.coupling.side1)

The intent is that when the user has familiarized with this syntax it is faster to read and produced a cleaner looking code

[mrdobalina2k]

I think normally in programming languages >> or << refers to bit-shifts.

[mrdobalina2k]

Do these new methods/classes have documentation already?

[LasseNT]

They have a very basic docstring.

[mrdobalina2k]

can this docstring be expanded beyond the basic one?

[mrdobalina2k]

Why do you need @EquationSpec here and not @equation ?

[LasseNT]

The equation spec allows passing of the instance of the ScopeSpec which internally adds the equation to the namespace mechanics. In this way the previous code of add_to_namespace can be omitted, while it is still explicit that the equation is connected to the namespace.

[mrdobalina2k]

could you add a parameter, 'equation_spec', to the @equation decorator instead of creating a new equation decorator?

[mrdobalina2k]

I think some description is needed, rather than only the code. Like what are we trying to solve here? And why do you chose this method over the "standard" numerous syntax with Subsystem etc.

[LasseNT]

Yes, I think a dedicated documentation file introducing the concept should be added before the next release.

[LasseNT]

Also there is a short bullet list in the description of this pull request.

[mrdobalina2k]

I suggest adding r""" strings at the top of the example, which can later be parsed by sphinx to create an example gallery. I think there's no time as the present, and best that we add this before the final approval. This is a major release after all.

[mrdobalina2k]

a late reply, but better late than never.

[mrdobalina2k]

could you add a parameter, 'equation_spec', to the @equation decorator instead of creating a new equation decorator?

[mrdobalina2k]

I think normally in programming languages >> or << refers to bit-shifts.

[mrdobalina2k]

I suggest adding r""" strings at the top of the example, which can later be parsed by sphinx to create an example gallery. I think there's no time as the present, and best that we add this before the final approval. This is a major release after all.