From 6c3d07791a6273b40ee4a7bff4041f59183adc99 Mon Sep 17 00:00:00 2001
From: Christopher Ruwisch <christopher.ruwisch@gmail.com>
Date: Mon, 10 Mar 2025 20:31:04 +0100
Subject: [PATCH] initial docu for airfoils and aixml/endnode
---
.../documentation/libraries/airfoils/index.md | 98 +++++++++
.../aixml/endnode/getting-started.md | 46 ++++
.../libraries/aixml/endnode/index.md | 132 ++++++++++++
.../libraries/aixml/endnode/valid_units.md | 59 ++++++
docs/documentation/libraries/aixml/index.md | 11 +
docs/documentation/libraries/index.md | 199 ------------------
6 files changed, 346 insertions(+), 199 deletions(-)
create mode 100644 docs/documentation/libraries/airfoils/index.md
create mode 100644 docs/documentation/libraries/aixml/endnode/getting-started.md
create mode 100644 docs/documentation/libraries/aixml/endnode/index.md
create mode 100644 docs/documentation/libraries/aixml/endnode/valid_units.md
create mode 100644 docs/documentation/libraries/aixml/index.md
delete mode 100644 docs/documentation/libraries/index.md
diff --git a/docs/documentation/libraries/airfoils/index.md b/docs/documentation/libraries/airfoils/index.md
new file mode 100644
index 0000000..fbecc65
--- /dev/null
+++ b/docs/documentation/libraries/airfoils/index.md
@@ -0,0 +1,98 @@
+# The `Airfoils` library
+
+**Description:**
+This file is part of UNICADO. It implements the `Airfoils` class which manages airfoil data stored in files. The class provides functionality to load airfoil files from a specified directory, print the available airfoils, retrieve airfoil polygon data, and copy airfoil files to a target directory.
+
+---
+
+## Class: Airfoils
+
+### Overview
+- **Purpose:** Manages airfoil data by loading airfoil files from a directory and providing methods to interact with them.
+- **Key Responsibilities:**
+ - Load airfoil data from a given directory.
+ - Maintain a collection (`available_airfoils`) that maps airfoil names to their file paths.
+ - Provide methods to print, retrieve, and copy airfoil data.
+
+---
+
+### Constructor
+
+#### `Airfoils(const std::filesystem::path& path_to_airfoil_directory)`
+- **Description:**
+ Initializes the `Airfoils` object by loading airfoil files from the provided directory.
+- **Parameters:**
+ - `path_to_airfoil_directory`: Filesystem path to the directory containing airfoil files.
+- **Behavior:**
+ - Checks if the provided directory exists.
+ - If not, throws an error using `throwError` with a formatted message.
+ - Calls the private method `add_directory_airfoils(path_to_airfoil_directory)` to populate the `available_airfoils` map.
+
+---
+
+### Public Methods
+
+#### `void print_available_airfoils()`
+- **Description:**
+ Prints the list of available airfoils with their names and file paths.
+- **Behavior:**
+ Iterates over the `available_airfoils` map and prints each entry using formatted output.
+ Uses `std::cout` or a runtime logging stream (`myRuntimeInfo->out`) if available.
+
+---
+
+#### `geom2::Polygon_2 get_airfoil(const std::string& airfoil)`
+- **Description:**
+ Retrieves the polygon data of the specified airfoil.
+- **Parameters:**
+ - `airfoil`: Name of the airfoil.
+- **Returns:**
+ A `geom2::Polygon_2` object representing the airfoil's polygon data.
+- **Behavior:**
+ - Searches for the airfoil in the `available_airfoils` map.
+ - If the airfoil is not found, throws an error.
+ - Otherwise, reads and returns the airfoil data using `geom2::io::read_airfoil`.
+
+---
+
+#### `void copy_available_airfoil(const std::string& airfoil, const std::filesystem::path& target_directory)`
+- **Description:**
+ Copies the specified airfoil file to a target directory.
+- **Parameters:**
+ - `airfoil`: Name of the airfoil.
+ - `target_directory`: Filesystem path to the destination directory.
+- **Behavior:**
+ - Checks if the target directory exists; if not, throws an error.
+ - Validates that the airfoil is available in the `available_airfoils` map; if not, throws an error.
+ - Compares the absolute paths of the source (airfoil file) and the target directory.
+ - If they are the same, logs that the copying is skipped.
+ - Attempts to copy the airfoil file using `std::filesystem::copy` with the `update_existing` option.
+ - Catches any exceptions during copying and rethrows them using `throwError`.
+
+---
+
+### Private Methods
+
+#### `void add_directory_airfoils(const std::filesystem::path& path_to_airfoil_directory)`
+- **Description:**
+ Adds all airfoil files from the specified directory to the `available_airfoils` map.
+- **Parameters:**
+ - `path_to_airfoil_directory`: Filesystem path to the directory containing airfoil files.
+- **Behavior:**
+ - Verifies that the directory exists; if not, throws an error.
+ - Iterates over each entry in the directory using `std::filesystem::directory_iterator`.
+ - For each entry, calls the private method `add_airfoil(entry.path())`.
+
+---
+
+#### `void add_airfoil(const std::filesystem::path& airfoil_path)`
+- **Description:**
+ Adds a single airfoil file to the `available_airfoils` map.
+- **Parameters:**
+ - `airfoil_path`: Filesystem path to the airfoil file.
+- **Behavior:**
+ - Checks if the file exists; if not, throws an error.
+ - Verifies that the path is a regular file and has a `.dat` extension.
+ - Extracts the airfoil name (using the filename's stem) and inserts it into the `available_airfoils` map.
+
+---
diff --git a/docs/documentation/libraries/aixml/endnode/getting-started.md b/docs/documentation/libraries/aixml/endnode/getting-started.md
new file mode 100644
index 0000000..2fde1e1
--- /dev/null
+++ b/docs/documentation/libraries/aixml/endnode/getting-started.md
@@ -0,0 +1,46 @@
+# How to use the Endnode
+This section gives simple examples on how to use an endnode.
+
+!!! note
+ The values and variables are for tutorial purpose only
+
+## Creating and using a numeric endnode
+
+```cpp
+// Example: Create a numeric endnode for a value representing length in meters.
+Endnode<double> lengthNode("/path/to/wanted/endnode", "Aircraft Length", 10.0, "m", 5.0, 20.0);
+
+// Read from an XML node
+lengthNode.read(xml_node);
+
+// Update the value and then update the XML node
+lengthNode.set_value(12.5);
+lengthNode.update(xml_node);
+
+```
+
+## Creating and using a non-numeric endnode
+
+```cpp
+// Example: Create a string endnode for an aircraft model identifier.
+Endnode<std::string> modelNode("/path/to/string/endnode", "Aircraft Model", "A320");
+
+// Read and print the node
+modelNode.read(xml_node);
+modelNode.print();
+```
+
+## Creating and using a read-only Endnode
+// Example: Create a read-only endnode for a boolean
+
+```cpp
+EndnodeReadOnly<bool> readOnlyNode("/path/to/boolean/endnode");
+
+// Read the XML data
+readOnlyNode.read(xml_node);
+
+// Print both the parsed and original XML values
+// This will have only effect if it's working on a numeric node and if the numeric node is a none SI (but valid)
+readOnlyNode.print_xml();
+```
+
diff --git a/docs/documentation/libraries/aixml/endnode/index.md b/docs/documentation/libraries/aixml/endnode/index.md
new file mode 100644
index 0000000..3560f66
--- /dev/null
+++ b/docs/documentation/libraries/aixml/endnode/index.md
@@ -0,0 +1,132 @@
+# The `endnode` in UNICADO
+
+The `endnode` is a main access point to the aircraft exchange file and lets you interface the different nodes (leafs) in an easy way. This class is build on top of the aixml class (no inheritance) which is used for raw access of xml file content.
+
+## Overview
+
+The `endnode` implements templated classes that define an endnode as a part of an XML document. An `endnode` is the final element in a node hierarchy, representing a leaf node that contains a value and in the case of numeric nodes, its associated unit, lower and upper boundaries.
+
+The classes support:
+
+- **Numeric types** (any arithmetic type except `bool`)
+- **Boolean types** (`bool`)
+- **String type** (`std::string`)
+
+Each variant comes with its own constructors and methods to read from or update XML nodes. For numeric types, additional checks ensure that the value remains within specified boundaries and that units are valid according to SI or allowed custom conversions.
+
+## Code Structure
+
+### Concept: `is_numeric`
+
+- **Purpose:**
+ Defines a concept that accepts arithmetic types excluding `bool`.
+- **Usage:**
+ Used to restrict template instantiation for numeric operations.
+
+```cpp
+template <typename T>
+concept is_numeric = (std::is_arithmetic<T>::value && (!std::is_same<T, bool>::value));
+```
+
+For `std::string` and `bool` the concept is_numeric is used with logic operators:
+### For boolean:
+
+- **Purpose:**
+ Adapts is_numeric concept that accepts bool type.
+- **Usage:**
+ Used to restrict template instantiation for numeric operations.
+
+```cpp
+template <typename T>
+!is_numeric<T> && std::is_same<T, bool>::value
+```
+
+### For strings:
+
+- **Purpose:**
+ Adapts is_numeric that accepts strings.
+- **Usage:**
+ Used to restrict template instantiation for std::string operations.
+
+```cpp
+template <typename T>
+!is_numeric<T> && std::is_same<T, std::string>::value
+```
+
+
+### Class: EndnodeBase
+
+**Template Parameter:**
+- `T` - the type of value the endnode holds (arithmetic, bool, or std::string).
+
+**Responsibilities:**
+- Provides common functionality for reading XML node attributes.
+- Initializes node paths and default values.
+- Implements methods for:
+ - Reading node content from an XML node.
+ - Printing node values.
+ - Checking and converting units (for numeric types).
+ - Validating that a numeric value lies within defined boundaries.
+
+**Constructors:**
+- Overloaded to handle numeric types, booleans, and strings.
+- Allows setting default values, units, and boundaries.
+
+**Key Methods:**
+- `read(const node& xml)`: Reads XML node data.
+- `print()`: Prints the node's content.
+- `check_boundaries()`: Ensures numeric values are within allowed limits.
+- `check_unit()`: Validates unit correctness and handles custom-to-SI conversion if needed.
+- `convert_items()`: Converts values to SI units when a custom unit is used.
+
+**Internal Data Members:**
+- `description_`: A string description of the node.
+- `paths`: A vector of strings storing the XML path parts.
+- `value_`, `lower_boundary_`, `upper_boundary_`: Numeric values (for numeric types).
+- `unit_`: The unit associated with the numeric value.
+- Several constant collections for SI units and unit conversion factors.
+
+---
+
+### Class: Endnode
+
+**Inheritance:**
+- Derives from `EndnodeBase<T>`.
+
+**Purpose:**
+- Provides a concrete implementation of an endnode with capabilities to read from and update an XML node.
+
+**Additional Methods:**
+- `update(node& xml)`: Updates the XML node with the current values. Different overloads exist for numeric, boolean, and string types.
+- Overloaded arithmetic operators (`+=`, `-=`, `*=`, `/=`) for numeric types.
+- Assignment operators to easily update values or boundaries.
+- Setter methods for changing the node’s value, unit, and boundaries.
+
+**Usage Scenario:**
+- Use this class when you need to modify XML data – both reading from and writing to an XML document.
+
+---
+
+### Class: EndnodeReadOnly
+
+**Inheritance:**
+- Also derived from `EndnodeBase<T>`.
+
+**Purpose:**
+- Represents an XML endnode whose value is read-only after the initial XML read.
+
+**Differences from Endnode:**
+- Stores original XML values in separate members (`value_xml_`, `unit_xml_`, etc.).
+- Provides methods to print or retrieve the raw, unparsed XML data.
+
+**Key Methods:**
+- `read(const node& xml)`: Reads the XML data and stores both parsed and original (XML) values.
+- `print_xml()`: Prints the original XML values (format differs for numeric and non-numeric types).
+- Getters to access the raw XML values directly.
+
+
+
+The `EndnodeReadOnly` is mainly used for configuration files since those data should not be altered by the module. For classic access and updating, use the Endnode class.
+
+!!! danger "Important"
+ None SI units will be converted automatically to SI units by the given table in the endnode.h file when reading. Have a look at valid units in [valid units](valid_units.md)
diff --git a/docs/documentation/libraries/aixml/endnode/valid_units.md b/docs/documentation/libraries/aixml/endnode/valid_units.md
new file mode 100644
index 0000000..a19850b
--- /dev/null
+++ b/docs/documentation/libraries/aixml/endnode/valid_units.md
@@ -0,0 +1,59 @@
+# Allowed SI Units and how it is converted
+
+### SI Units Table
+
+| Unit | Description |
+|--------|-------------------------------|
+| m | meter |
+| m^2 | squaremeter |
+| m^3 | cubicmeter |
+| m/s | meter per second |
+| rad | radian |
+| 1 | no unit |
+| Pa | pascal |
+| kg | kilogram |
+| kg/s | kilogram per second |
+| kg/Ns | kilogram per newton second |
+| s | second |
+| J | Joule |
+| J/kg | Joule per kilogram |
+| J/m^3 | Joule per cubic meter |
+| W | Watt |
+| V | volt |
+| A | ampere |
+| N | newton |
+| N/m^2 | newton per square meter |
+| kg/m^2 | kilogram per square meter |
+| kg/m^3 | kilogram per cubic meter |
+| kgm^2 | kilogram square meter |
+| K | Kelvin |
+| EUR | Euro |
+| US | Dollar |
+
+### Custom to SI Units Conversion Table
+
+| Custom Unit | SI Unit |
+|--------------|---------|
+| deg | rad |
+| ft | m |
+| FL | m |
+| NM | m |
+| lbs | kg |
+| lbs/min | kg/s |
+| EUR | EUR |
+| US | US |
+| g | 1 |
+| dBA | Pa |
+| EPNdB | Pa |
+| Sone | Pa |
+| h | s |
+| min | s |
+| a | s |
+| ft/min | m/s |
+| kts | m/s |
+| KCAS | m/s |
+| l | m^3 |
+| Celsius | K |
+| micro meter | m |
+| kg/h | kg/s |
+
diff --git a/docs/documentation/libraries/aixml/index.md b/docs/documentation/libraries/aixml/index.md
new file mode 100644
index 0000000..c1d085a
--- /dev/null
+++ b/docs/documentation/libraries/aixml/index.md
@@ -0,0 +1,11 @@
+# The aixml library
+
+This library purpose is to interact with xml files, especially for accessing xml files like the aircraft exchange file and the module configuration files.
+
+## Aixml
+
+This library contains methods for "raw" accessing of xml files based on the tinyxml library
+
+## Endnode
+
+This library contains template classes especially for the usage in UNICADO and should be used in each C++ module for easy accessing nodes.
diff --git a/docs/documentation/libraries/index.md b/docs/documentation/libraries/index.md
deleted file mode 100644
index 479b8dd..0000000
--- a/docs/documentation/libraries/index.md
+++ /dev/null
@@ -1,199 +0,0 @@
----
-title: Libraries
-summary: Overview of the libraries respository
-authors:
- - Sebastian Oberschwendtner
- - Kristina Mazur
-date: 2024-11-28
-glightbox: false
----
-
-As mentioned in the [build instructions](../../get-involved/build-instructions/build/general.md), we have some external dependencies to:
-
-- :simple-cplusplus: [Eigen3 :octicons-link-external-16:](https://eigen.tuxfamily.org/index.php?title=Main_Page){:target="_blank"}
-- :simple-cplusplus: [Boost :octicons-link-external-16:](https://www.boost.org/){:target="_blank"}
-- :simple-cplusplus: [CGAL :octicons-link-external-16:](https://www.cgal.org/){:target="_blank"}
-- :simple-python: [pipenv :octicons-link-external-16:](https://pipenv.pypa.io/en/latest/){:target="_blank"} (not really a library, more a environment manager tool)
-
-
-!!! note
- Currently, only `aircraftGeometry2` and `engine` are documented.
-
-## aerodynamics
-{.overview-img align=left}
-This library helps with interacting with polar data.
-It has helper functions to extract and interpolate data of provided airfoil polars.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
-
----
-
-## aircraftGeometry2
-{.overview-img align=left}
-This library is based on the older aircraftGeometry library and extends it to be more modular.
-The modularity and flexibility is achieved by using the high performance [:octicons-link-external-16: Computational Geometry Algorithms Library](https://www.cgal.org/) also known as **CGAL**.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|[Link](aircraftGeometry2/index.md)| [Eigen3](https://eigen.tuxfamily.org/index.php?title=Main_Page), [CGAL](https://www.cgal.org/)|
-
----
-
-## airfoils
-{.overview-img align=left}
-The **airfoils** libary provides a database for different airfoils.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
-
----
-
-## aixml
-{.overview-img align=left}
-The **aixml** library is the central library which handles the XML files and data access.
-It uses a simple XML library, namely *tinyxml*, to read and parse the XML files.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
-
----
-
-## atmosphere
-{.overview-img align=left}
-The **atmosphere** library provides helper functions to calculate atmospheric properties according to the International Standard Atmosphere (*ISA*).
-You can set different atmospheric conditions (e.g. *ISA+25*) and calculate the physical properties of the air at different altitudes.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-||
-
----
-
-## blackboxTest
-{.overview-img align=left}
-The **blackboxTest** library provides an interface to run a complete module with different test cases and then checks whether a specific result is calculated or set compared to expected values defined in a `blackBoxTestCases.xml`. The tests are realized with the help of the _googleTest_ framework .
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|[googleTest](https://google.github.io/googletest/)|
-
----
-
-## engine
-{.overview-img align=left}
-This library helps with interacting with engine data.
-It has helper functions to extract and interpolate data of provided engine data decks.
-The engine decks can originate from different softwaretools as long as they provide the same file format.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|[Link](engine/index.md)|-|
-
----
-
-## extern
-UNICADO currently uses two external libaries as submodules:
-
-- `doxygen-awesome-css` for documentation formation [(see here)](https://github.com/jothepro/doxygen-awesome-css.git)
-- `pybind11` to use C++ libraries in the python tools [(see here)](https://github.com/pybind/pybind11.git)
-
----
-
-## liftingLineInterface
-{.overview-img align=left}
-This library helps with interacting with results provided by the tools **Lifting Line** from DLR.
-It has helper functions to extract and interpolate data of the results from the tool.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
-
----
-
-## moduleBasics
-{.overview-img align=left}
-This library provides the basis structure for the modular approach of the **UNICADO** tools.
-The tools are intended to follow the *Strategy Design Pattern* to execute at different fidelity levels.
-The library gives a template how modules should be structured and gives helpers which can be used to select and implement the different fidelity methods.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
-
----
-
-## pymodulepackage
-{.overview-img align=left}
-This library provides standardized UNICADO data preprocessing, run, and postprocessing functions for Python modules.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-python: |GPLv3|-|-|
-
----
-
-## runtimeInfo
-{.overview-img align=left}
-This library handles the user interface during the modules execution.
-In provides custom output streams, which automatically handle the log files and error outputs according to the configuration files.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
-
----
-
-## standardFiles
-{.overview-img align=left}
-This library provides file interfaces and interacts with the operating system.
-It can handle process execution with a simple interface.
-The library can handle *UNIX* and *Windows* systems alike.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
-
-!!! warning
- Some functions of this library are a bit outdated! When using this library, please look first at the wonderful [STL :octicons-link-external-16:](https://en.cppreference.com/w/) whether the function you are seeking is already there.
-
----
-
-## svl
-{.overview-img align=left}
-The `simple vector library` by Andrew Willmott provides vector and matrix classes.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: | |[Link](https://www.cs.cmu.edu/~ajw/doc/svl.html)|-|
-
-!!! note
- This will soon be replaced by `Eigen`.
-
----
-
-## unitConversion
-{.overview-img align=left}
-The **unitConversion** groups the most commonly used unit in aerospace and let's you convert values from one unit to another.
-In addition, it defines some common **constants** which are useful for calculations.
-{.overview-item}
-
-|Module Version|Language|License|Documentation|Dependencies|
-|:---:|:---:|:---:|---|---|
-|0.5.0|:simple-cplusplus: |GPLv3|-|-|
\ No newline at end of file
--
GitLab