picmi-standard / picmi

Standard input format for Particle-In-Cell codes
https://picmi.readthedocs.io
Other
35 stars 25 forks source link

add developer documentation and design principles #72

Open s9105947 opened 2 years ago

s9105947 commented 2 years ago

New section "Developer Documentation" is aimed at developers wanting to work on PICMI itself. Its content may be of interest to implementors, but should not be required knowledge to them.

The design principles outlines fundamental design decisions and aims to clarify misunderstandings on PICMI at an early stage.


Key points that are important to me personally:

s9105947 commented 2 years ago

Note: I am not that familiar with the rst format, feel free to make suggestions.

s9105947 commented 2 years ago

I've proofread and would put considers this document "done", at least for the basics.

I summon @dpgrote @ax3l @BrianMarre for their opinions!

ax3l commented 2 years ago

Users are not allowed to access attributes directly.

I have no problem with that point. The only thing we should note is that writing attributes directly can invoke undefined behavior (inconsistent objects if not all corresponding members are updated). Reading is actually no issue, unless we want to hide unit conversions within.

ax3l commented 2 years ago

@s9105947 @BrianMarre just a minor question to clarify above, if you have a chance :)

BrianMarre commented 2 years ago

Yes it probably is a good idea to note that writing to attributes causes undefined behaviour, and yes I agree that reading should not cause problems, as in both will probably not cause and should under no circumstances cause problems by design.

Edit: I did change my mind somewhat, we should discourage the user from needlessly reading variables but it should not be disallowed in general