Using the Heat Load and Flow Rate Modules

Geoloop allows the BHE simulation to use time-varying thermal demand (heat load) and time-varying circulation flow rates, either defined synthetically or read from external data files.

The input JSON file for these module is directly used for a calculation of the time-variable heat load by the Loadprofile module or for a calculation of the time-variable flow rate by the FlowData module. Both have a command in the CLI of calculate-loadprofile or calculate-flowdata respectively (see Geoloop Interface).

Alternatively, for configuration of these modules, a file is linked in the main configuration JSON under the keys loadprofile or flow_data respectively.

The heat load profile determines the time-dependent thermal power demand Q (in W), while the flow rate profile determines the mass flow rate m_flow (in kg/s). Both can be configured independently. If only one is variable, the other may remain constant.

Passing a variable load profile to the simulation is only possible when running an imposed heat load on the system (run_type in the main simulation configuration is POWER). Passing a variable flow rate to the simulation is only possible when running a simulation with a constant inlet temperature (run_type in the main simulation configuration is TIN).

Configuration of the Heat Load and Flow Rate Modules

The input JSON file for the loadprofile and flowdata modules have a similar structure with the following input parameters:

Configuration Parameters for the Heat Load

Parameter	Description	Unit	Type	Remark
lp_type	Type of heat load profile	-	sting	Options: BERNIER; CONSTANT; VARIABLE; FROMFILE
lp_inputdir	Path to folder containing the heat load source file	—	string	-
lp_outdir	Path to output directory for generated profiles and figures	—	string	Creates folder if not existing
lp_filename	Name of the input CSV file containing the heat load data	—	string	The fourth row in the file must contain the column names; Optional; only used if `lp_type` is FROMFILE
lp_inputcolumn	Name of the column in the input file that contains the heat load data	-	string	Heat load data in unit kW; Optional; only used if `lp_type` is FROMFILE
lp_smoothing	Type of smoothing applied to the load data	—	string	Options: D (daily), M (monthly), Y (yearly). Optional; only used if `lp_type` is FROMFILE
lp_scale	Scaling factor applied to the load values	—	scalar	Scaling factor for the load profile. Optional; only used if `lp_type` is FROMFILE
lp_minscaleflow	Minimum scaling factor for flow rate	-	scalar	To avoid very lowe flowrates affecting numerical performance. Optional; only used if `lp_type` is FROMFILE or VARIABLE
lp_minQ	Minimum heat demand (absolute)	-	scalar	Below lo_minQ the heat demand is set to 0 to avoid numerical performance issues. Optional; only used if `lp_type` is FROMFILE
lp_peak	Peak heat load	W	scalar	Optional; only used if `lp_type` is VARIABLE
lp_base	Base heat load	W	scalar	Optional; only used if `lp_type` is VARIABLE

Required fields depend on lp_type:
"CONSTANT" → requires lp_base
"VARIABLE" → requires lp_base and lp_peak
"FROMFILE" → requires lp_filename, lp_inputdir, lp_minscaleflow, lp_minQ, lp_scale

Configuration Parameters for the Flow Rate

Parameter	Description	Unit	Type	Remarks
fp_type	Type of flow profile	-	string	Options: CONSTANT; VARIABLE; FROMFILE
fp_inputdir	Path to folder containing the flow rate profile souce file	—	string	Only required when using FROMFILE
fp_outdir	Path to output directory for saving processed/smoothed profiles	—	string	Created if not existing
fp_filename	Name of the CSV file containing time-varying flow rate data	—	string	Only required when `fp_type = FROMFILE`
fp_inputcolumn	Name of the column containing mass flow data	-	string	Default: `m_flow`, only used when FROMFILE
fp_scale	Global scaling factor applied to the flow profile	—	float	Optional; useful for scenario scaling
fp_smoothing	Temporal smoothing option	—	string or integer	Options: integer window in hours, or M (monthly), D (daily). Optional.
fp_base	Base flow rate	kg/s	float	Only used if `fp_type = VARIABLE` or `CONSTANT`
fp_peak	Peak flow rate	kg/s	float	Only used if `fp_type = VARIABLE`

Required fields depend on fp_type: - "CONSTANT" → requires fp_peak - "VARIABLE" → requires fp_base and fp_peak - "FROMFILE" → requires fp_filename, fp_inputcolumn, fp_inputdir, fp_scale

Path Resolution in the Heat Load and Flow Rate Modules

When loading heat load or flow rate data from a file (**_type is FROMFILE), the paths to the data files (**_filepath) are resolved according to the following rules during configuration initiation:

Directories are created if needed.
**_filepath = config_folder / **_inputdir / **_filename

Types of Heat Load and Flow Rate Time-Profiles

The heat load module can calculate several types of synthetic heat load and flow rate profiles (defined with the configuration parameters lp_type and fp_type). These include a constant heat load or flow rate ("CONSTANT"), a variable heat load or flow rate following a cosine ("VARIABLE") and a variable heat load according to the method of Bernier et al. (2004) (lp_type = "BERNIER"). Alternatively, a pre-defined hourly-variable heat load or flow rate profile can be loaded from a file ("FROMFILE").

The column with heat load or flow rate data is defined in the **_inpucolumn parameters. For a variable heat load, an example of such a file is provided in the input subdirectory of the working directory of the example from a BHE field in the city of Madrid. For a variable flow rate, an example of such a file is provided in the input subdirectory of the working directory of the example from a BHE with a daily-variable flow rate profile

NOTE: The heat load in the CSV datafile has unit kW and the first four rows in the datafile are considered header lines; make sure the column names are defined in row 4.

NOTE: The simulation internally operates on a uniform time array, which is generated based on the parameters nyear and nled in the main simulation configuration. Both heat load and flow rate profiles are interpolated or indexed to match this simulation time array.

When using a pre-defined heat load or flow rate profile, it is possible to apply a smoothing factor over time, that averages short-term fluctuations. The smoothing can be applied in a daily or monthly interval and is defined by the configuration parameter **_smoothing. For an example of using a smoothed heat load, see the example of a BHE field in the Middle East. In addition, the pre-defined heat load or flow rate can be scaled using the parameter **_scale. For the heat load this scaling factor represents the dwelling equivalent (DE) of power. I.e. the heat load is increased by a factor that is equal to the amount of extra dwellings that are supplied.

NOTE: To apply a smoothing factor to the pre-defined heat load or flow rate profile, a column named "local_time" is required in the input CSV file, that includes the timestamps for the data column.

For a predefined or analytically generated heat load profile (e.g., cosine-based), the flow rate is scaled proportionally to the instantaneous heat load. The parameter m_flow represents the maximum flow rate, which is reached when the absolute heat load is at its peak.

At each time step, the flow rate is computed by normalizing the absolute heat load with respect to its maximum value and multiplying it by m_flow. This results in a flow rate profile that follows the magnitude of the load.

To avoid unrealistically low or zero flow rates, a minimum scaling factor is enforced via lp_minscaleflow. As a result, the flow rate never drops below lp_minscaleflow * m_flow.

Heat load profiles can represent heating, cooling, or variable operation modes.

Outputs

When using a pre-defined heat load profile, a plot of the load over time is automatically created. The plot is stored in a fixed file-name format, in the output directory of the heat load module.

For a simulation without smoothing applied to the heat load, output includes:

/json_outdir/{lp_filename}.png

For a simulation with smoothing applied to the heat load, output includes:

/json_outdir/{lp_filename}_ + D/M +_smoothing.png

Here, D/M refers to a daily or monthly smoothing factor respectively.

When using a pre-defined flow rate profile, the data is plotted according to the plotting configuration for the time-plot of the flow rate (see section below). For a simulation that includes a smoothing factor over time, imposed on the flow rate profile, a .CSV file is created that includes the flow rate values in the smoothed time resolution and is stored in a fixed file-name format.

/json_outdir/flow_ + monthly/daily +.csv

References

Bernier, M., Labib, R., Pinel, P., and Paillot, R.: A Multiple load aggregation algorithm for annual hourly simulations of GCHP systems, HVAC and R Research, 10, 471–487, 2004.