diff --git a/.gitignore b/.gitignore index 990f8eb..08cf438 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,5 @@ /zero_engine opencode.Containerfile compose.yaml - +/site .venv diff --git a/README.md b/README.md index 74d29c6..b976329 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,19 @@ +# LUX ENERGY TWIN DOCUMENTATION -Source of [docs.lux.energy](https://docs.lux.energy) +This repository contains the code for the user and the technical documentation for LUX Energy Twin, or LUX for short. + +For those just interested in reading the docs, they can be easily accessed at [docs.lux.energy](https://docs.lux.energy). + +The rest of this file is for those interested in contributing to the docs. + +The documentation guidelines can be found in the file: `documentation_guidelines`. + +The documentation is automatically deployed to the LUX website so that it is always up to date with the status of this repository. + +When developping the results can be viewed locally by running the following command: + +``` +podman run --volume .:/app docker.io/javanile/mkdocs:latest sh -c "pip3 install pymdown-extensions && mkdocs build" +``` + +This produces html files in the folder `site`, which can be opened in your browser of choice. \ No newline at end of file diff --git a/documentation_guidelines.md b/documentation_guidelines.md new file mode 100644 index 0000000..28775b5 --- /dev/null +++ b/documentation_guidelines.md @@ -0,0 +1,40 @@ +# Documentation Guidelines + +This document is aimed to help you create documentation pages that match the structure and style of our docs. \ +The documentation is in markdown files \( \.md \), the basic syntax of which can be found [here](https://www.markdownguide.org/basic-syntax/) + +## What should be documented? + +Any sufficiently important Agent, Class or Function in the LUX model. The scope of the LUX model is: the engine, loader, interface, resultsUI and projectTemplate. + +Sufficiently important is ofcourse a subjective statement, but as a rule of thumb: + +> If a piece of code is of vital importance to the workings of the model, or contains assumptions that have significant impact on the model results it should be documented. + +## Structure of a documentation page + +All documentation pages should try to follow the same structure. The page should contain at least the following information: + +* A (short) introduction on the piece of code. How does it fit into the model's architecture. What function does it fulfil in the model. +* If it is a class or agent, what are the most important parameters & variables? For each of those describe why it is of importance. You may also want to describe where the choice of parameter is determined or where it is used by the class. +* If it is a class or agent, what are the most important functions & methods? For each of those describe why it is of importance. + +## Styling + +* Every page should start with a title, which is added by starting a line with a \# (Level 1 heading). +* A page may contains paragraphs, which are added by lines starting with \#\# (Level 2 heading). +* Small code snippits that fit inline and names of variables, classes, functions, etc. must be displayed between backticks \( \` \) \ +For example: `p_timeVariables.updateTimeVariables(v_timeStepsElapsed, p_timeParameters);` +* Larger code snippits that span multiple lines must be displayed as fenced code blocks between three backticks \( \`\`\` \) \ +You can also specify the language of the code after the first three backticks, e.g. \`\`\`java \ +The result looks like this: +```java +for (GridConnection gc : c_gridConnections) { + gc.f_calculateEnergyBalance(p_timeVariables, v_isRapidRun); +} +``` +* Functions discriptions are code snippits, hence displayed between backticks. \ +Functions may list all their arguments, some of their arguments, or none of their arguments. \ +Arguments that are omitted are replaced with three dots \( \.\.\. \) \ +Usually from the arguments both the type and name is mentioned, the variable name is only mentioned in larger code snippits where it is relevant or when there is ambiguity , so not in function descriptions. \ +For example in `J_RapidRunData`: `addTimeStep( J_FlowsMap fm_currentBalanceFlows_kW, J_FlowsMap fm_currentConsumptionFlows_kW, ... , J_TimeVariables timeVariables)` diff --git a/site/engine/consistency_checks/index.html b/site/engine/consistency_checks/index.html index 68b7e0a..3f153f0 100644 --- a/site/engine/consistency_checks/index.html +++ b/site/engine/consistency_checks/index.html @@ -138,31 +138,31 @@

Consistency Checks

-

The LUX engine applies several consistency checks to ensure a correct and leak-free energy balance.

+

The LUX engine applies several consistency checks to ensure a correct model.

Configuration Check

The configuration check validates the model setup before simulation. It is implemented as f_checkConfiguration() methods on the EnergyModel and GridConnections.

The EnergyModel's f_checkConfiguration() iterates over all GridConnections and calls their individual check.

-

The GridConnection's f_checkConfiguration() checks:

+

The GridConnection's f_checkConfiguration() checks for:

-

This ensures that every agent with flexible equipment has a valid control system assigned before the simulation runs.

+

This ensures that every agent with flexible assets has a valid control system assigned before the simulation runs.

Energy Balance Check

The energy balance check (implemented as f_performEnergyBalanceCheck() on the EnergyModel) verifies the law of conservation of energy: energy cannot be created or destroyed in the model.

Energy can only enter or leave the model through these paths:

The balance equation is:

-
Production - Export = Consumption - Import = SelfConsumption
+
Production - Export = Consumption - Import

In code, the check computes:

double energyBalanceCheck_MWh = totalImport_MWh + totalProduction_MWh
     - (totalExport_MWh + totalConsumption_MWh + totalDeltaStoredEnergy_MWh);
-

This value must be zero. If it exceeds a tolerance of 1e-6 MWh, a warning is logged. The check also accounts for changes in stored energy (battery charge state, thermal storage in buildings) to prevent false positives from energy buffers that are not empty at the end of the simulation.

+

This value must be zero. If it exceeds a tolerance of 1e-6 MWh, a warning is logged. The check also accounts for changes in stored energy (battery charge state, thermal storage in buildings) to prevent false positives from energy buffers that the same at the end of the simulation compared to the start.