SIM-VICUS and NANDRAD Developers Manual

There are build scripts for different VC and Qt versions. To keep things simple, all developers should install the same VC and Qt versions on development machines.

Required versions:

Installation steps:

Also, install a suitable git client (SmartGit is recommendet). Don’t forget to specify your git user name and email (user settings).

On Linux it’s a walk in the park. Just install the build-essential package (g++/clang and cmake and qt5default packages). On Ubuntu simply run:

Also, install git or a suitable git client (SmartGit is recommendet). Don’t forget to specify your git user name and email:

On El Capitan (MacOSX 10.11) Qt 5.11.3 is the last version to work. So you need to manually download this version. First select the Qt online installer (https://www.qt.io/download-qt-installer) and select version 5.11.3. This ensures that all developers use the same Qt version and avoid Qt-specific compilation problems.

Parallel gcc OpenMP code require a bit of extra work (to be documented later :-)

Also, install git or a suitable git client (SmartGit is recommendet). Don’t forget to specify your git user name and email:

To trace the source of an error, keeping an exception trace is imported. When during simulation init you get an exception "Invalid unit ''" thrown from IBK::Unit somewhere, you’ll have a hard time tracing the source (also, when this is reported as error by users and debugging isn’t easily possible).

Hence, if you call a function that might throw, wrap it into a try-catch clause and throw on:

The error message stack will then look like:

That should narrow it down a bit.

Accessing not initialized member variables or even worse, accessing member variables initialized with default values (hereby skipping over mandatory initialization steps), can be hard to track during development/debugging.

Hence initialize variables that need to be initialized with values you will recognized. Using C++11 features, you should write code like:

See https://doc.qt.io/qtcreator/creator-editor-refactoring.html for a comprehensive list!

Make use of the refactoring feature (right-click on a symbol/variable/function/switch…​) and select "Refacture" in the context menu.

Useful features are:

NANDRAD creates model objects on the heap during initialization (never during solver runtime!). Since the model objects are first initialized before ownership is transferred, you should always ensure proper cleanup in case of init exceptions. Use code like:

If there is code between creation and ownership transfer, use code like:

Under the condition that Jacobian matrixes for Dense and KLU are identical, the simulation should also run - theoretically - with identical results and solver statistics, only a bit slower in the case of the Dense matrix. Hence, it is a good first test to run the same test case with both matrix solvers and check, if there are significant differences.

When running a test case with the following options:

this will generate two sets of output directories with (hopefully) identical physical results and statistics. However, even if the Jacobian pattern used by the sparse matrix solver is 100% correct, the rounding errors related to the LU factorization of the dense matrix, or the factorization of the re-arranged sparse matrix will likely give minor changes in the Newton solution which may accumulate over time and cause small differences in counters.

Still, the test can be done automated by running the script run_JacobianPatternTest.sh in the build/cmake directory.

The script will run all test cases with Dense and KLU solvers, compare results and statistics and flag all test cases with differences as failed.

Once a test case has been manually checked, a file with suffix jac_checked instead of nandrad can be placed side-by-side the NANDRAD project file. For all test cases with such a jac_checked file, the test will be skipped and the case will be marked as successful.

The sparse Jacobian pattern can be checked by comparing it against a full dense Jacobian matrix. If the sparse pattern is correct, the generated Jacobian matrixes must be identical, under the following conditions:

To generate the Jacobians to compare, the following changes need to be made in the solver’s source code:

Now you can generate the Jacobians for a specific test case using the command

This will run the test case with KLU and Dense (the latter with ImplicitEuler integrator) and then rename the dumped Jacobians to test_jacobian_dense.bin and test_jacobian_sparse.bin.

Now open these files with the JacobianMatrixViewer tool (see https://github.com/ghorwin/JacobianMatrixViewer).

If the matrixes match, you can run the script:

which will create the test.jac_checked file and also remove the bin-files.

Some basic error checking can be made in the NANDRAD Project data structure that is independent of the actual simulation-dependend model setup. These tests are done in functions called checkParameters().

Basically, the NANDRAD Model calls these checkParameters() functions for all data objects. The functions should check for sane values (i.e. positive cross-section areas, non-negative coefficients, and generally all parameters with known limits. Also, the existence of parameters when required should be tested (in sofar this is independent of specific modelling options).

Error handling shall be done in such a way, that when parameter errors are found, the user can quickly identify the offending XML tag and fix the problem.

Note, that in the exception the index, optional display name and ID is printed - one of these should be sufficient to find the problematic XML block.

The location of error is reported by the calling function, inside the checkParameters() function it is sufficient to indicate the actual parametrization error:

The exception hierarchy will be collected in the IBK::Exception objects and printed in the error stack (see also Exception handling).

For (the very frequently occurring) IBK::Parameter data type, the checkedValue() is most convenient to both check for existence and validity of an IBK::Parameter (including matching units). The function also returns the value in the requested target unit (see documentation for IBK::Parameter::checkedValue()).

Access of model parameters is very fast during simulation, if looping and searching through the data structure can be avoided. Pointers between data structures are an efficient way of relating data objects. For example, a construction layer references the respective material data via ID number of the material. During the initialization (specifically in checkParameters() a pointer is obtained to the material and stored in the object. This requires, of course, that the pointer may never become invalidated during the life-time of the simulation. Hence the strict requirement of not-changing vector sizes (see above).

If a references data element is missing, an error message is thrown (this is part of the reason, why this lookup of referenced data objects is done and checked in checkParameters().

The Loads model is a pre-defined model that is always evaluated first whenever the time point has changed. It does not have any other dependencies.

It provides all resulting variables as constant (during iteration) result variables, which can be retrieved and utilized by any other model.

With respect to solar radiation calculation, during initialization it registers all surfaces (with different orientation/inclination) and provides an ID for each surface. Then, models can request direct and diffuse radiation data, as well as incidence angle for each of the registered surfaces.

Each construction surface (interface) with outside radiation loads registers itself with the Loads object, hereby passing the interface object ID as argument and orientation/inclination of the surface. The loads object itself registers this surface with the climate calculation module (CCM) and retrieves a surface ID. This surface ID may be the same for many interface IDs.

The Loads object stores a mapping of all interface IDs to the respective surface IDs in the CCM. When requesting the result variable’s memory location, this mapping is used to deliver the correct input variable reference/memory location to the interface-specific solar radiation calculation object.

The model instances/objects must tell the solver framework what kind of outputs they generate. Objects generating results must derive from class AbstractModel (or derived helper classes) and implement the abstract interface functions.

The framework first requests a reference type (prefix) via AbstractModel::referenceType() of the model object. This reference type is used to group model objects into meaningful object groups.

Each invididual result variable is published by the model in an object of type QuantityDescription. The framework requests these via call to AbstractModel::resultDescriptions(). Within the QuantityDescription structure, the model stores for each computed quantity the following information:

The unit is really only provided for error message outputs and for checking of the base SI unit matches the base SI unit of the requested unit (as an additional sanity check).

Sometimes, a model may compute a vector of values.

When a so-called vector-valued quantity is generated, the following additional information is provided:

Each model object is requested by the framework in a call to AbstractModel::initResults() to reserve memory for its result variables. For scalar variables this is usually just resizing of a vector of doubles to the required number of result values. For vector-valued quantities the actual size may only be known later, so frequently here just the vectors are created and their actual size is determined later.

When FMI export is defined, i.e. output variables are declarted in the FMI interface, a list of global variable IDs to be exported is defined. For each of these variables an input reference is generated (inside the FMIInputOutput model), just as for any other model as well.

When initializing outputs, any published variable can be collected. Outputs declare their input variables just as any other model object.

Later, when the framework connects model inputs with results, the framework requests models to provide persistant memory locations for previously published results. This is done by calling AbstractModel::resultValueRef(), which get’s a copy of the previously exported InputReference.

In order to uniquely identify a result variable within a model, normally only two things are needed:

However, in some cases, a model may request a variable with the same quantity name, yet from two different objects (for example, the air temperature of neighbouring zones). In this case, the quantity name alone is not sufficient. Hence, the full input reference including object ID is passed as identifier (A change from NANDRAD 1!).

Naturally, for scalar result variables the index/id property is ignored.

The QuantityName struct contains this information (a string and an integer value).

Now the model searches through its own results and tries to find a matching variable. In case of vector-valued quantities it also checks if the requested id is actually present in the model, and in case of index-based access, a check is done if the index is in the allowed range (0…​size-1).

If a quantity could be found, the corresponding memory address is returned, otherwise a nullptr. The framework now can take the address and pass it to any object that requires this input.

To uniquely reference a resulting variable (and its persistent memory location), first the actual model object/instance need to be selected with the following properties:

Some model objects exist only once, for example schedules or climatic loads. Here, the reference-type is already enough to uniquely select the object.

Usually, the information above does select several objects that have been created from the parametrization related to that ID. For example, the zone parameter block for some zone ID generates several zone-related model instances, all of which have the same ID. Since their result variables are all different, the framework simply searches through all those objects until the correct variable is found. These model implementations can be thought of as one model whose equations are split up into several implementation units.

The actual variable within the selected object is found by ID name and optionally vector-element id/index, as described above.

The data is collected in the class InputReference:

Also, it is possible to specify a constant flag to indicate, that during iterations over cycles the variable is to be treated constant.

Any input variable requested by any other model can be overridden by FMU import variables. When the framework looks up global model references, and an FMU import model is present/parametrized, then first the FMI generated quantity descriptions are checked. The FMU import variables are exported as global variable references (with ObjectReference). Since these are then the same global variable identifiers as published by the models, they are found first in the search and dependent models will simply store points to the FMU variable memory.

See also explanation in https://www.learnopengles.com/tag/triangle-strips.

See polygon in Figure 3. Index list to draw the polygon is:

When drawing several triangle strips one after another, we need primitive restart (to have gaps between triangles).

Consider strips in Figure 4. Top part of the figure shows two strips where the first strip ends with an odd numbered triangle. Bottom part shows the first strip ending with an even numbered triangle.

Uniform color, no lighting effect, no transparency

Valid polygons have the following properties:

When drawing a polygon or starting with a given set of vertexes, we can remove vertexes that would violate any of the rules above in the following manner:

Dies erstellt die übliche Verzeichnisstruktur unter: /home/ghorwin/git/SIM-VICUS/data/fmu/coSimulation.msim.

Jetzt kann man den Debugger starten (F5) und man müsste MasterSim durchlaufen sehen.

Wenn man im QtCreator irgendwo einen Breakpoint setzt, und dann in der Debugger-Module-Ansicht die geladenen Shared Libraries ansieht, kann man diesen Pfad wiederfinden.

Beispiel:

Löscht man die "alte" FMU Bibliothek aus dem binaries/linux64-Verzeichnis erhält man eine Fehlermeldung, z.B.

Shared library '/home/ghorwin/git/SIM-VICUS/data/fmu/coSimulation/fmus/singleRoom/binaries/linux64/singleRoom.so' does not exist.

Man erstellt nun einen Symlink auf die aktuell entwickelte FMU-Bibliothek an Stelle der originalen FMU-Bibliothek, welche von MasterSim geladen wird.

Im Verzeichnis: /home/ghorwin/git/SIM-VICUS/data/fmu/coSimulation/fmus/singleRoom/binaries/linux64/:

Dies erstellt eine symbolische Verknüpfung zur gerade entwickelten Bibliothek libNandradSolverFMI.so.

Wenn man nun den Debugger startet, lädt MasterSim stattdessen diese aktuelle Bibliothek. Damit der symbolische Link nicht wieder überschrieben wird, muss das Argument --skip-unzip verwendet werden.

Nun kann man die FMU ganz normal debuggen.