There are certain behaviors of AiiDA (often related to provenance) that users frequently find counterintuitive or frustrating. For instance, immutability of nodes once they are stored, in combination with the fact that they automatically become stored when e.g. passed to a calcfunction. This is the subject of the discussion on the immutability of the new StructureData class (see here). One idea brought up in the past (see here) there was to make the behavior "consistent", for instance by making StructureData (and other AiiDA nodes) fully immutable by default. However, such approaches can become impractical, and might eventually be less user-friendly (as noted in the discussion).
Describe the solution you'd like
Rather than trying to change these behaviors (and the way AiiDA implements provenance), I think it could be a much easier solution to just clearly highlight them in one centralized, easy-to-find location in the documentation. As these are general concepts of AiiDA, they should appear very "early" in a user's journey (possibly even before the basic tutorial). I am sure they are all mentioned in the documentation, however, scattered through the massive amount of material that is available. The most important concepts should be concisely mentioned at a high level.
The name of the proposed doc was thought of together with @mikibonacci, but is open for discussion, as it might be offensive to some people.
Some ideas for the points communicated could be (text possibly still too technical):
All AiiDA data and process classes inherit from Node. Node is the base class that provides functionality for recording of provenance and storage in the database.
Unstored Nodes are, in principle, mutable. However, they become immutable once stored in the database to ensure provenance.
Operating on an AiiDA Node using an AiiDA process, for instance through a @calcfunction, automatically stores the Node in the database. Again, this is done to ensure provenance.
AiiDA stores nodes and provenance in an SQL database (PostgreSQL / SQLite). In addition, files are stored in what is referred to as a "repository" (implemented via the disk-objectstore). By default, individual files are stored as is in a "loose" directory, but they can be concatenated to larger individual files in a "packed" directory with via storage maintenance operations ([documentation here(https://aiida.readthedocs.io/projects/aiida-core/en/latest/internals/storage/repository.html#the-disk-object-store)) for easier backup and transfer.
Difference between User, Profile, etc.
etc.
Curios to hear your thoughts @khsrali, @agoscinski, @mikibonacci, @mbercx, @giovannipizzi, @sphuber. Thanks!
Describe the current issue
There are certain behaviors of AiiDA (often related to provenance) that users frequently find counterintuitive or frustrating. For instance, immutability of nodes once they are stored, in combination with the fact that they automatically become stored when e.g. passed to a
calcfunction. This is the subject of the discussion on the immutability of the newStructureDataclass (see here). One idea brought up in the past (see here) there was to make the behavior "consistent", for instance by makingStructureData(and other AiiDA nodes) fully immutable by default. However, such approaches can become impractical, and might eventually be less user-friendly (as noted in the discussion).Describe the solution you'd like
Rather than trying to change these behaviors (and the way AiiDA implements provenance), I think it could be a much easier solution to just clearly highlight them in one centralized, easy-to-find location in the documentation. As these are general concepts of AiiDA, they should appear very "early" in a user's journey (possibly even before the basic tutorial). I am sure they are all mentioned in the documentation, however, scattered through the massive amount of material that is available. The most important concepts should be concisely mentioned at a high level.
The name of the proposed doc was thought of together with @mikibonacci, but is open for discussion, as it might be offensive to some people.
Some ideas for the points communicated could be (text possibly still too technical):
Node.Nodeis the base class that provides functionality for recording of provenance and storage in the database.Nodes are, in principle, mutable. However, they become immutable once stored in the database to ensure provenance.Nodeusing an AiiDA process, for instance through a@calcfunction, automatically stores theNodein the database. Again, this is done to ensure provenance.Curios to hear your thoughts @khsrali, @agoscinski, @mikibonacci, @mbercx, @giovannipizzi, @sphuber. Thanks!