@@ -6,96 +6,5 @@ Comprehensive explanations of core concepts and advanced topics in `aiida-atomis
66:maxdepth: 2
77
88properties
9- immutability
109storage_backends
11- structure_of_the_code
12- ```
13-
14- ## Core Concepts
15-
16- ### 🏗️ ** Property Types and Architecture**
17-
18- Understanding the property system in aiida-atomistic:
19- - ** Guide** : [ Property Types] ( properties.md )
20- - ** Topics** : Global vs site vs computed properties, property formats, naming conventions
21- - ** Why it matters** : Understanding how to access and use structure properties effectively
22-
23- ** Key takeaways:**
24- - Individual site properties (singular: ` charge ` , ` magmom ` ) vs computed arrays (plural: ` charges ` , ` magmoms ` )
25- - Global properties apply to entire structure (` pbc ` , ` cell ` , ` hubbard ` )
26- - Computed properties are derived on-the-fly (` formula ` , ` kinds ` , ` dimensionality ` )
27- - Statistical properties for efficient queries (` max_charge ` , ` min_magmom ` , etc.)
28- - Clear property access patterns and formats
29-
30- ### 🔒 ** Immutability**
31-
32- Understanding the immutability model and its implications:
33- - ** Guide** : [ Immutability in StructureData] ( immutability.md )
34- - ** Topics** : Immutable vs mutable structures, frozen data types, best practices
35- - ** Why it matters** : Data provenance, workflow reproducibility, AiiDA integration
36-
37- ** Key takeaways:**
38- - ` StructureData ` is immutable for provenance tracking
39- - ` StructureDataMutable ` for construction and modification
40- - How to work with frozen lists and sites
41- - Converting between mutable and immutable structures
42-
43- ### 💾 ** Storage Backends**
44-
45- Understanding data storage strategies:
46- - ** Guide** : [ Storage Backends] ( storage_backends.md )
47- - ** Topics** : Attribute-based vs repository-based storage, metadata-driven decisions, querying
48- - ** Why it matters** : Choosing the right backend for performance and scalability
49-
50- ** Key takeaways:**
51- - ` StructureData ` : All data in database attributes (queryable, simple)
52- - ` StructureDataRepository ` : Arrays in ` .npz ` files, metadata in database (scalable)
53- - Metadata controls storage location (` store_in="db" ` vs ` store_in="npz" ` )
54- - Trade-offs between queryability and storage efficiency
55-
56- ### ⚙️ ** Code Architecture**
57-
58- Internal structure and organization of the codebase:
59- - ** Guide** : [ Structure of the Code] ( structure_of_the_code.md )
60- - ** Topics** : Module organization, class hierarchy, design patterns
61- - ** For** : Developers extending or contributing to aiida-atomistic
62-
63- ## Advanced Topics
64-
65- ### Property System Details
66-
67- How properties are implemented:
68- - ** Site properties** : Stored in ` Site ` model, accessed via ` sites[i].property `
69- - ** Computed arrays** : Aggregated from sites using ` @computed_field ` decorators
70- - ** Global properties** : Stored in ` StructureBaseModel ` , apply to whole structure
71- - ** Validation** : Pydantic field validators and model validators
72-
73- ### Performance Optimizations
74-
75- Structure operations and storage efficiency:
76- - ** Kind-based storage** : Compress repeated atoms for database efficiency
77- - ** Computed field caching** : Automatic memoization of expensive calculations
78- - ** Efficient copying** : Specialized methods for deep/shallow copies
79- - ** Lazy evaluation** : Properties computed only when accessed
80-
81- ### Validation System
82-
83- Ensuring data integrity:
84- - ** Field-level validation** : Pydantic validators for each property
85- - ** Cross-property validation** : Model validators for consistency checks
86- - ** Kind validation** : Ensuring sites with same kind have same properties
87- - ** Site proximity checks** : Detecting atoms too close together
88- - ** Tolerance system** : Configurable precision for property comparisons
89-
90- ## Related Documentation
91-
92- - ** [ How-to Guides] ( ../how_to/index.md ) ** : Step-by-step instructions for common tasks
93- - [ Creating Structures] ( ../how_to/creation_mutation.md )
94- - [ Working with Kinds] ( ../how_to/kinds.md )
95- - [ Magnetic Structures] ( ../how_to/magnetic_structures.md )
96- - [ Adding Properties] ( ../how_to/dev_adding_properties.md )
97- - [ Plugin Migration] ( ../how_to/dev_plugin_migration.md )
98-
99- - ** [ Tutorials] ( ../tutorials/index.md ) ** : Learn by example with complete workflows
100-
101- - ** [ Reference] ( ../reference/api/index.md ) ** : Detailed API documentation
10+ ```
0 commit comments