diff --git a/.clang-uml b/.clang-uml new file mode 100644 index 00000000..9d18b76a --- /dev/null +++ b/.clang-uml @@ -0,0 +1,285 @@ +compilation_database_dir: build +output_directory: docs/diagrams/puml +diagrams: + timeintegration: + type: class + generate_method_arguments: full + generate_packages: false + glob: + - core/**/*.cpp + - physics/**/*.cpp + relative_to: src + package_type: directory + include: + paths: + - core + - physics + elements: + - RKmethod + - ButcherTableau + - DynamicEquation + - RungeKuttaStepper + - "RungeKuttaStepper##RungeKuttaStageExecutor" + - Stepper + - TimeSolver + - Relaxer + exclude: + namespaces: + - std + plantuml: + before: + - '!theme vibrant' + - 'left to right direction' + - 'package Legend {' + - ' class Class' + - ' abstract class Abstract' + - ' enum Enum' + - ' class Visibility {' + - ' +public field' + - ' +public method()' + - ' -private field' + - ' -private method()' + - ' #protected field' + - ' }' + - ' Class -[hidden]-> Extension' + - ' Abstract -[hidden]-> Extension' + - ' Enum -[hidden]-> Extension' + - ' Visibility <|-- Extension : Extension' + - ' Visibility o-- Aggregation : Aggregation' + - ' Visibility +.. Nested : Nested' + - ' Visibility --> Dependency : Dependency' + - ' Visibility ..> WeakDependency : Weak dependency' + - '}' + + magnetics: + type: class + generate_method_arguments: full + generate_packages: false + glob: + - core/**/*.cpp + - physics/**/*.cpp + relative_to: src + package_type: directory + include: + paths: + - core + - physics + elements: + - Altermagnet + - Antiferromagnet + - DmiTensor + - CuDmiTensor + - Ferromagnet + - HostMagnet + - Magnet + - Minimizer + - MumaxWorld + - NcAfm + - BoundaryTraction + - CuBoundaryTraction + exclude: + namespaces: + - std + plantuml: + before: + - '!theme vibrant' + - 'left to right direction' + - 'package Legend {' + - ' class Class' + - ' class Visibility {' + - ' +public field' + - ' +public method()' + - ' -private field' + - ' -private method()' + - ' }' + - ' Class -[hidden]-> Extension' + - ' Visibility <|-- Extension : Extension' + - ' Visibility o-- Aggregation : Aggregation' + - ' Visibility --> Dependency : Dependency' + - ' Visibility ..> WeakDependency : Weak dependency' + - '}' + + quantities: + type: class + generate_method_arguments: full + generate_packages: false + glob: + - core/**/*.cpp + - physics/**/*.cpp + relative_to: src + package_type: directory + include: + paths: + - core + - physics + elements: + - "DynamicParameter" + - Field + - CuField + - FieldQuantity + - InterParameter + - Parameter + - CuParameter + - VectorParameter + - CuVectorParameter + - ScalarQuantity + - Variable + - NormalizedVariable + - "ScalarQuantityEvaluator" + - "FieldQuantityEvaluator" + exclude: + namespaces: + - std + plantuml: + before: + - '!theme vibrant' + - 'left to right direction' + - 'package Legend {' + - ' class Class' + - ' abstract class Abstract' + - ' class Template ' + - ' class Visibility {' + - ' +public method()' + - ' -private field' + - ' -private method()' + - ' #protected field' + - ' #protected method()' + - ' }' + - ' Class -[hidden]-> Extension' + - ' Abstract -[hidden]-> Extension' + - ' Template -[hidden]-> Extension' + - ' Visibility <|-- Extension : Extension' + - ' Visibility o-- Aggregation : Aggregation' + - ' Visibility --> Dependency : Dependency' + - ' Visibility ..> WeakDependency : Weak dependency' + - '}' + + strayfield: + type: class + generate_method_arguments: full + generate_packages: false + glob: + - physics/**/*.cpp + relative_to: src + package_type: directory + include: + paths: + - core + - physics + elements: + - StrayFieldExecutor + - StrayField + - StrayFieldBruteExecutor + - StrayFieldFFTExecutor + - StrayFieldKernel + exclude: + namespaces: + - std + plantuml: + before: + - '!theme vibrant' + - 'left to right direction' + - 'package Legend {' + - ' class Class' + - ' abstract class Abstract' + - ' class Visibility {' + - ' +public method()' + - ' -private field' + - ' #protected field' + - ' #protected method()' + - ' }' + - ' Class -[hidden]-> Extension' + - ' Abstract -[hidden]-> Extension' + - ' Visibility <|-- Extension : Extension' + - ' Visibility o-- Aggregation : Aggregation' + - '}' + + domain: + type: class + generate_method_arguments: full + generate_packages: false + glob: + - core/**/*.cpp + - physics/**/*.cpp + relative_to: src + package_type: directory + include: + paths: + - core + - physics + elements: + - Grid + - System + - CuSystem + - World + exclude: + namespaces: + - std + plantuml: + before: + - '!theme vibrant' + - 'left to right direction' + - 'package Legend {' + - ' class Class' + - ' class Visibility {' + - ' +public method()' + - ' -private field' + - ' #protected field' + - ' }' + - ' Class -[hidden]-> Dependency' + - ' Visibility o-- Aggregation : Aggregation' + - ' Visibility --> Dependency : Dependency' + - '}' + + utilities: + type: class + generate_method_arguments: full + generate_packages: false + glob: + - core/**/*.cpp + - physics/**/*.cpp + - linsolver/**/*.cpp + - bindings/wrap_mfm.cpp + relative_to: src + package_type: directory + include: + paths: + - core + - physics + - linsolver + elements: + - VoronoiTessellator + - Center + - Tile + - Int3Hash + - MFM + - PoissonSystem + - LinSolver + - "LinSolver##Stepper" + - LinearSystem + - "LinearSystem##CuData" + exclude: + namespaces: + - std + plantuml: + before: + - '!theme vibrant' + - 'left to right direction' + - 'package Legend {' + - ' class Class' + - ' abstract class Abstract' + - ' class Visibility {' + - ' +public field' + - ' +public method()' + - ' -private field' + - ' -private method()' + - ' #protected method()' + - ' }' + - ' Class -[hidden]-> WeakDependency' + - ' Abstract -[hidden]-> WeakDependency' + - ' Visibility o-- Aggregation : Aggregation' + - ' Visibility +.. Nested : Nested' + - ' Visibility --> Dependency : Dependency' + - ' Visibility ..> WeakDependency : Weak dependency' + - '}' + \ No newline at end of file diff --git a/.gitignore b/.gitignore index 2ca58dd2..5f431235 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ cu*_*.dll docs/_build/* !docs/_build/html/ !docs/_build/html/** +docs/diagrams/puml diff --git a/README.md b/README.md index 86a719f3..fd3bd464 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ It follows the [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/for make html ``` -The documentation can then be found at `docs/_build/html/index.html`. +The documentation can then be found at `docs/_build/html/index.html`. However, to generate the class diagrams you should be on a Linux device and first install [clang-uml](https://github.com/bkryza/clang-uml/tree/master) otherwise they will not be generated. ## Examples diff --git a/cpp_class_diagram.drawio b/cpp_class_diagram.drawio deleted file mode 100644 index cb1cba73..00000000 --- a/cpp_class_diagram.drawio +++ /dev/null @@ -1,701 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/class_diagrams.rst b/docs/class_diagrams.rst new file mode 100644 index 00000000..9b9512c2 --- /dev/null +++ b/docs/class_diagrams.rst @@ -0,0 +1,17 @@ +:nosearch: + +Class Diagrams +============== + +These sections will show you the C++ class diagrams of mumax⁺. The classes are split +in 6 main groups to maintain a clear overview. + +.. toctree:: + :maxdepth: 1 + + diagrams/quantities + diagrams/magnetics + diagrams/strayfield + diagrams/timeintegration + diagrams/domain + diagrams/utilities \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 698e7c1e..445bb4e6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,6 +9,10 @@ import os import sys import datetime +import subprocess +import shutil +import warnings +import platform sys.path.insert(0, os.path.abspath("../mumaxplus")) @@ -33,7 +37,8 @@ "sphinxcontrib.video", "sphinx_copybutton", "sphinx.ext.napoleon", - "sphinx_design" + "sphinx_design", + "sphinxcontrib.plantuml" ] toc_object_entries_show_parents = 'hide' @@ -82,6 +87,8 @@ html_js_files = [ ('https://www.googletagmanager.com/gtag/js?id=G-YEPT1QRBRH', {'async': 'async'}), 'google-analytics.js', + 'js/svg-pan-zoom.min.js', + 'js/setup-pan-zoom.js', ] html_favicon = "_static/nimble-plus.png" @@ -125,4 +132,26 @@ ], "icon_links_label": "Quick Links", # screen reader label "use_download_button": False, -} \ No newline at end of file +} + +def setup(app): + project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + subprocess.run([ + "cmake", + "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON", + "-B", "build" + ], check=True, cwd=project_root) + + clang_resource_dir = subprocess.check_output( + ["clang", "-print-resource-dir"], text=True + ).strip() + + subprocess.run([ + 'clang-uml', + '--add-compile-flag', f'-resource-dir={clang_resource_dir}' + ], cwd=project_root) + +plantuml = "plantuml" + +plantuml_output_format = 'svg_img' \ No newline at end of file diff --git a/docs/diagrams/domain.rst b/docs/diagrams/domain.rst new file mode 100644 index 00000000..2315ce10 --- /dev/null +++ b/docs/diagrams/domain.rst @@ -0,0 +1,8 @@ +:nosearch: + +Domain +====== + +UML diagram of ``CuSystem``, ``Grid``, ``System``, ``World``. + +.. uml:: ./puml/domain.puml \ No newline at end of file diff --git a/docs/diagrams/magnetics.rst b/docs/diagrams/magnetics.rst new file mode 100644 index 00000000..acaeb29c --- /dev/null +++ b/docs/diagrams/magnetics.rst @@ -0,0 +1,8 @@ +:nosearch: + +Magnetics +========= + +UML diagram of ``Altermagnet``, ``Antiferromagnet``, ``BoundaryTraction``, ``CuBoundaryTraction``, ``CuDmiTensor``, ``DmiTensor``, ``Ferromagnet``, ``HostMagnet``, ``Magnet``, ``Minimizer``, ``MumaxWorld``, ``NcAfm``. + +.. uml:: ./puml/magnetics.puml \ No newline at end of file diff --git a/docs/diagrams/quantities.rst b/docs/diagrams/quantities.rst new file mode 100644 index 00000000..34386bb4 --- /dev/null +++ b/docs/diagrams/quantities.rst @@ -0,0 +1,8 @@ +:nosearch: + +Quantities +========== + +UML diagram of ``CuField``, ``CuParameter``, ``CuVectorParameter``, ``DynamicParameter``, ``Field``, ``FieldQuantity``, ``FieldQuantityEvaluator``, ``InterParameter``, ``NormalizedVariable``, ``Parameter``, ``ScalarQuantity``, ``ScalarQuantityEvaluator``, ``Variable``, ``VectorParameter``. + +.. uml:: ./puml/quantities.puml \ No newline at end of file diff --git a/docs/diagrams/strayfield.rst b/docs/diagrams/strayfield.rst new file mode 100644 index 00000000..aa150503 --- /dev/null +++ b/docs/diagrams/strayfield.rst @@ -0,0 +1,8 @@ +:nosearch: + +Strayfield +========== + +UML diagram of ``StrayField``, ``StrayFieldBruteExecutor``, ``StrayFieldExecutor``, ``StrayFieldFFTExecutor``, ``StrayFieldKernel``. + +.. uml:: ./puml/strayfield.puml \ No newline at end of file diff --git a/docs/diagrams/timeintegration.rst b/docs/diagrams/timeintegration.rst new file mode 100644 index 00000000..a624abc8 --- /dev/null +++ b/docs/diagrams/timeintegration.rst @@ -0,0 +1,8 @@ +:nosearch: + +Time Integration +================ + +UML diagram of ``ButcherTableau``, ``DynamicEquation``, ``Relaxer``, ``RKmethod``, ``RungeKuttaStepper``, ``RungeKuttaStepper::RungeKuttaStageExecutor``, ``Stepper``, ``TimeSolver``. + +.. uml:: ./puml/timeintegration.puml \ No newline at end of file diff --git a/docs/diagrams/utilities.rst b/docs/diagrams/utilities.rst new file mode 100644 index 00000000..690a330c --- /dev/null +++ b/docs/diagrams/utilities.rst @@ -0,0 +1,8 @@ +:nosearch: + +Utilities +========= + +UML diagram of ``Center``, ``Int3Hash``, ``LinearSystem``, ``LinearSystem::CuData``, ``Linsolver``, ``Linsolver::Stepper``, ``MFM``, ``PoissonSystem``, ``Tile``, ``VoronoiTessellator``. + +.. uml:: ./puml/utilities.puml \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 9f3ceed2..90b470d4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,4 +47,9 @@ Contents .. toctree:: :maxdepth: 2 - examples \ No newline at end of file + examples + +.. toctree:: + :maxdepth: 2 + + class_diagrams \ No newline at end of file diff --git a/environment.yml b/environment.yml index 1527533c..3bae447c 100644 --- a/environment.yml +++ b/environment.yml @@ -1,6 +1,8 @@ name: mumaxplus channels: + - bkryza/label/clang-uml - conda-forge + - defaults dependencies: # required - python=3.13 @@ -20,23 +22,29 @@ dependencies: - isort # check that imports are in the right order - pre-commit - pip - - pip: - - clang-format # optional - ipython - jupyter - ipywidgets - pyvista + - vtk - pillow # should be contained in matplotlib - pandas - - pip: - - pyovf # documentation generation + - clang + - clang-uml + - plantuml - sphinx - sphinx-book-theme - numpydoc - sphinxcontrib-video - sphinx-copybutton - sphinx-design + + # pip blocks + - pip: + - clang-format # code checks + - pyovf # optional + - sphinxcontrib.plantuml # documentation generation