Skip to content

Commit 0c97bf0

Browse files
authored
docs: enhance and restructure documentation for base and FM models (#1007)
docs: enhance and restructure documentation for base and FM models - Reorganized documentation structure for better readability - Added overview and diagrams for the `base` module and research model architecture - Introduced FM model documentation with supporting diagrams and structure overview - Improved cross-references between sections - Updated Jupyter MkDocs plugin and refreshed example notebook
1 parent 0a9dd29 commit 0c97bf0

File tree

28 files changed

+2367
-135
lines changed

28 files changed

+2367
-135
lines changed

docs/reference/base/ini.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# INI format
2+
3+
The ini module provides the generic logic for parsing Deltares ini based files, such as the mdu, structures files, as well as more complex files such as the boundary condition (bc) files.
4+
5+
Note that specific attribute files that employ this ini format often have their own dedicated module (and separate API doc page). These include:
6+
7+
- [MDU file](../dflowfm/mdu/mdu.md) (`hydrolib.core.dflowfm.mdu`)
8+
- [External forcing file](../dflowfm/external-forcing/ext.md) (`hydrolib.core.dflowfm.ext`)
9+
- [Initial fields and parameter file](../dflowfm/external-forcing/inifield.md) (`hydrolib.core.dflowfm.inifield`)
10+
- [Structure file](../dflowfm/external-forcing/structure.md) (`hydrolib.core.dflowfm.structure`)
11+
- [1D roughness](../dflowfm/cross-sections/friction.md) (`hydrolib.core.dflowfm.friction`)
12+
- [Cross section files](../dflowfm/cross-sections/crosssection.md) (`hydrolib.core.dflowfm.crosssection`)
13+
- [Storage node file](../dflowfm/topology-network/storagenode.md) (`hydrolib.core.dflowfm.storagenode`)
14+
15+
Following below is the documentation for the INI format base classes.
16+
17+
## Model
18+
19+
::: hydrolib.core.dflowfm.ini.models
20+
21+
## Parser
22+
23+
::: hydrolib.core.dflowfm.ini.parser
24+
25+
## Serializer
26+
27+
::: hydrolib.core.dflowfm.ini.serializer

docs/reference/base/overview.md

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
```mermaid
2+
3+
classDiagram
4+
%% Base Classes
5+
class BaseModel {
6+
+Config
7+
+__init__(data: Any)
8+
+is_file_link(): bool
9+
+is_intermediate_link(): bool
10+
+show_tree(indent=0)
11+
+_apply_recurse(f, *args, **kwargs)
12+
+_get_identifier(data: dict): Optional[str]
13+
}
14+
15+
class FileModel {
16+
+is_file_link()
17+
+is_intermediate_link()
18+
+filepath: Path
19+
+load()
20+
+_should_load_model()
21+
+_post_init_load()
22+
+_resolved_filepath()
23+
+save_location()
24+
+_get_updated_file_path()
25+
+validate()
26+
+save()
27+
+synchronize_filepaths()
28+
+_save_tree(FileLoadContext, ModelSaveSettings)
29+
}
30+
class DiskOnlyFileModel {
31+
-_source_file_path: Path
32+
+filepath: Path
33+
+_post_init_load()
34+
+_load()
35+
+_save()
36+
+_can_copy_to()
37+
+is_intermediate_link()
38+
}
39+
40+
class ParsableFileModel{
41+
-serializer_config: SerializerConfig
42+
+_load()
43+
+_save()
44+
+_serialize()
45+
+dict()
46+
+_exclude_fields()
47+
}
48+
49+
class INIBasedModel {
50+
-string _header
51+
-FilePathStyleConverter _file_path_style_converter
52+
-regex _scientific_notation_regex
53+
-Comments comments
54+
+_get_unknown_keyword_error_manager()
55+
+_supports_comments()
56+
+_duplicate_keys_as_list()
57+
+get_list_delimiter()
58+
+get_list_field_delimiter()
59+
+_validate_unknown_keywords()
60+
+_skip_nones_and_set_header()
61+
+comments_matches_has_comments()
62+
+replace_fortran_scientific_notation_for_floats()
63+
+_replace_fortran_scientific_notation()
64+
+validate()
65+
+_exclude_from_validation()
66+
+_exclude_fields()
67+
+_convert_value()
68+
+_to_section()
69+
+_should_be_serialized()
70+
+_is_union()
71+
+_union_has_filemodel()
72+
+_is_list()
73+
+_value_is_not_none_or_type_is_filemodel()
74+
}
75+
76+
class DataBlockINIBasedModel {
77+
-Datablock datablock
78+
+as_dataframe()
79+
+_to_section()
80+
+_to_datablock()
81+
+_validate_no_nans_are_present()
82+
+_get_unknown_keyword_error_manager()
83+
+convert_value()
84+
+_validate_no_nans_are_present()
85+
+_is_float_and_nan()
86+
}
87+
88+
class INIModel {
89+
+serializer_config: INISerializerConfig
90+
+general: INIGeneral
91+
+_ext()
92+
+_filename()
93+
+_to_document()
94+
+_serialize()
95+
}
96+
97+
class INIGeneral {
98+
-Literal["General"] _header
99+
-string fileversion
100+
-string filetype
101+
+_supports_comments()
102+
}
103+
104+
class INISerializerConfig {
105+
+write_ini()
106+
}
107+
108+
class DataBlockINIBasedSerializerConfig {
109+
+serialize()
110+
+deserialize()
111+
}
112+
113+
class ModelSaveSettings {
114+
-_path_style: PathStyle
115+
-_exclude_unset: bool
116+
+path_style: PathStyle
117+
}
118+
119+
class ModelLoadSettings {
120+
-_recurse: bool
121+
-_resolve_casing: bool
122+
-_path_style: PathStyle
123+
+recurse: bool
124+
+resolve_casing: bool
125+
}
126+
127+
class FileLoadContext {
128+
+load_file(path: Path)
129+
+get_current_context()
130+
+initialize_load_settings()
131+
+load_settings()
132+
+retrieve_model()
133+
+register_model()
134+
+cache_is_empty()
135+
+get_current_parent()
136+
+resolve()
137+
+push_new_parent()
138+
+pop_last_parent()
139+
+resolve_casing()
140+
+convert_path_style()
141+
+is_content_changed()
142+
}
143+
144+
class FileModelCache {
145+
-_cache_dict: Dict[Path, CachedFileModel]
146+
+retrieve_model(path: Path): Optional[FileModel]
147+
+register_model(path: Path, model: FileModel)
148+
+is_empty(): bool
149+
+has_changed(path: Path): bool
150+
}
151+
152+
class CachedFileModel {
153+
-_model: FileModel
154+
-_checksum: str
155+
+model: FileModel
156+
+checksum: str
157+
}
158+
class ModelTreeTraverser {
159+
-should_traverse: Optional[Callable[[BaseModel, TAcc], bool]]
160+
-should_execute: Optional[Callable[[BaseModel, TAcc], bool]]
161+
-pre_traverse_func: Optional[Callable[[BaseModel, TAcc], TAcc]]
162+
-post_traverse_func: Optional[Callable[[BaseModel, TAcc], TAcc]]
163+
+traverse(model: BaseModel, acc: TAcc): TAcc
164+
}
165+
166+
class TAcc {
167+
<<TypeVar>>
168+
}
169+
170+
%% class ResolveRelativeMode {
171+
%% +ToParent: int
172+
%% +ToAnchor: int
173+
%% }
174+
175+
%% class FileCasingResolver {
176+
%% +resolve(path: Path): Path
177+
%% }
178+
179+
%% class FilePathResolver {
180+
%% -_anchors: List[Path]
181+
%% -_parents: List[Tuple[Path, ResolveRelativeMode]]
182+
%% +get_current_parent(): Path
183+
%% +resolve(path: Path): Path
184+
%% +push_new_parent(parent_path: Path, relative_mode: ResolveRelativeMode)
185+
%% +pop_last_parent()
186+
%% }
187+
188+
class UnknownKeywordErrorManager {
189+
+raise_error_for_unknown_keywords()
190+
}
191+
192+
class FileChecksumCalculator {
193+
+calculate_checksum(path: Path): str
194+
}
195+
196+
%% class FilePathStyleConverter {
197+
%% +convert(path: Path, style: PathStyle): Path
198+
%% }
199+
200+
%% class OperatingSystem {
201+
%% +WINDOWS: str
202+
%% +LINUX: str
203+
%% +MACOS: str
204+
%% }
205+
206+
%% class PathStyle {
207+
%% +POSIX: str
208+
%% +WINDOWS: str
209+
%% }
210+
211+
%% Inheritance Relationships
212+
FileModel <|-- DiskOnlyFileModel
213+
214+
BaseModel <|-- FileModel
215+
BaseModel <|-- INIBasedModel
216+
BaseModel <|-- CachedFileModel
217+
BaseModel <|-- ParsableFileModel
218+
ParsableFileModel <|-- FileModel
219+
220+
FileModelCache *-- CachedFileModel
221+
%% FilePathResolver *-- ResolveRelativeMode
222+
ModelTreeTraverser o-- TAcc
223+
224+
INIBasedModel <|-- DataBlockINIBasedModel
225+
INIBasedModel <|-- INIGeneral
226+
INIBasedModel <|-- INIModel
227+
INISerializerConfig <|-- DataBlockINIBasedSerializerConfig
228+
229+
%% Associations
230+
INIBasedModel --> UnknownKeywordErrorManager : manages
231+
%% INIBasedModel --> FilePathStyleConverter : uses
232+
INIBasedModel --> INISerializerConfig : serializes
233+
INIModel --> INIGeneral : contains
234+
INIModel --> INISerializerConfig : uses
235+
INIBasedModel --> FileModel : uses
236+
DataBlockINIBasedModel --> DataBlockINIBasedSerializerConfig : serializes
237+
DataBlockINIBasedModel --> ModelSaveSettings : uses
238+
DataBlockINIBasedModel --> INIBasedModel : extends
239+
FileLoadContext --> ModelLoadSettings : uses
240+
FileModel --> FileLoadContext : loads
241+
242+
FileModelCache *-- CachedFileModel
243+
FileLoadContext --> FileModelCache : uses
244+
FileLoadContext --> FileChecksumCalculator : uses
245+
246+
ParsableFileModel --> SerializerConfig : configures
247+
ParsableFileModel --> ModelSaveSettings : uses
248+
ParsableFileModel --> ModelLoadSettings : uses
249+
%% ModelSaveSettings --> PathStyle : sets
250+
%% ModelLoadSettings --> PathStyle : sets
251+
%% PathStyleValidator --> PathStyle : validates
252+
FileModelCache --> FileChecksumCalculator : verifies
253+
FileModel --> ModelTreeTraverser : uses
254+
255+
```
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

0 commit comments

Comments
 (0)