[WIP] Specify by Attributes

[s9105947]

Demonstrates intended transformation as described in #60.

See PICMI_Python/applied_fields.py as an example usage,
Test/unit/base.py for tests.

Not yet addressed issues (+solution):

• semantic checks
  • look for override-able check() method. If found, execute in constructor.
• custom vars for *analytic objects
  • add flag that can be set to enable custom vars
  • note: the syntax for the given equations is not defined, maybe define this first?
• breaks compatibility to [WIP]Handle unsupported #61
  • merge & adjust here
• offer shortcuts to numeric types, lists, (2D or 3D vectors?)
• provide documentation
• doc: add "howto calculations for dataclasses"

Arguable design decisions:

• __init__() can still be overwritten
• type annotations if not typing.Any are forbidden (b/c there are no typechecks enforced)
• using a codespecific attribute if not using that code (e.g. using warpx_bla in fbpic) is allowed and passes silently

[s9105947]

Before I go down the road of applying this to the entire codebase & implementing the open tasks listed above:

@dpgrote, if you could please have a look at the transformed definition of PICMI_ConstantAppliedField, is this a concept you can get behind? Should it be applied to the remaining standard?

@RemiLehe @ax3l

[dpgrote]

Sorry, but I am not enthusiastic about these changes. Overall, I find the code harder to read, with the list of input parameters spread out and not easy to visually scan (when looking something up for example). Does Sphinx/Doxygen understand this format when generating documentation? Also, the code for checking arguments is more complicated but doesn't seem to do anything more than what is already there, in handle_init method.

I understand the desire to have more type checking of the input parameters, but I don't think that the changes in this PR are the right way to go about it.

[dpgrote]

Thanks - to me, the pep257 style doc strings is cleaner.

BTW, does this need @autoclass before the class is defined?

[ax3l]

Thank you for adding unit tests. Definitely something this repo needs.

[ax3l]

For discussion on Monday:

• I am inclined to add this if it simplifies
  • checks Semantic & Syntactic Checking #59
  • adding new standardized PICMI parameters
  • adding new code-specific parameters: PICMI: warpx_file_min_digits ECP-WarpX/WarpX#2914
• Note that a style convention for self. parameters might be able to serve the same job.
• I am not sure that the example grid.nx = 1237 given in Specify Datastructures instead of Methods #60 is a real problem:
  • you cannot hide anything in Python, even _ and __ members are accessible
  • it might not be a problem at all that a user overwrites parameters after construction
  • we could apply "check()"s Semantic & Syntactic Checking #59 when we generate the file for a code in the backend, no need to run them for the constructor of
    things
  • as @dpgrote clarified with me: we should only store one member variable for the cells, not multiple

[s9105947]

This is roughly how I imagined the draft to look, could you please have a look and give me some feedback?

I have a way to handle custom variables in free expressions sketched on my whiteboard, will implement tomorrow (it does only require very little changes).

If we can agree on this draft I will start porting a first file entirely to this dataclass approach.

[s9105947]

Note to self: add documentation how to perform computations based on dataclasses

[dpgrote]

I've added PR #71 as a counter proposal to this PR. The changes made there are much smaller and lighter weight. Please take a look at it.

[ax3l]

Checked: pure python (incl. dependencies) & easy to install it seems

• https://pypi.org/project/typeguard/#files
• https://github.com/agronholm/typeguard/blob/master/pyproject.toml
• https://github.com/agronholm/typeguard/blob/master/setup.cfg

[ax3l]

note: hard to enforce API contract

[ax3l]

note: hard to enforce, maybe even error-prune API contract and maybe not ideal for something as common as __init__

[s9105947]

Discussed this concept with @dpgrote to a some depth.

I was under the false impression that PICMI provides a pure data structure (schema), and this PR makes a pure schema conveniently usable from Python. (Pretty much dataclass++)
This is not the case, PICMI is primarily an interface, hence the existence methods is not a problem.

Proposed way forward:

• Use PR [WIP] Added test of type checking and autoargs #71 to supply checks & cut boilerplate.
• Carry Tests & Documentation from this PR over into a new one (and adjust them).
• We discussed a general PICMI design document to clarify the misunderstanding outlined above (and more), PR will follow.

[ax3l]

@dpgrote as discussed recently, I think dataclasses could be the way to go, but going one step further and using pydantic #94 for validators and export of the API to other formats, e.g., toml/yaml/xml.

@s9105947 any opinion on #94?

[BrianMarre]

s910597 has most likely moved one

[BrianMarre]

@ax3l I quite like the pydantic approach, it seems to creates less boiler plate code than the pure typing approach we are using in the PIConGPU PICMI implementation.

And in the end I do not care what we use, so long as we get typing/type-checking