buildupp 0.0.6

Investigate structural build-up at rest in cementitious systems

buildupp — Structural build-up at rest in cementitious materials

The buildupp package supports investigations of structural build-up at rest in cementitious materials. It provides a specialized framework for analyzing coupled calorimetry and rheometry measurements (Michel et al. 2024, Michel et al. 2025).

By integrating hydration stoichiometry with physical powder properties (density, SSA, and PSD), buildupp allows to investigate how formation of hydration products results in stiffness increase, based on experimental data of fresh cement paste. While designed for blended cements (OPC, Limestone, Metakaolin), the architecture is easily extensible to any binder system.

---

Repository Structure

buildupp/ Core logic

• experiment.py: The primary API. It aligns calorimetry ($H, h$) and rheometry ($G'$) timelines, calculating hydration product thickness ($\Delta h_{prod}$) and solid volume fraction evolution ($\Delta \phi$).
• hydration.py: The thermodynamic engine. It uses Hess's law to derive reaction enthalpies and computes the mass ($\mu$) and volume ($\nu$) coefficients per Joule of heat.
• blend.py: Handles complex mixture compositions (e.g., '70opc30mk'). It calculates weighted PSDs, surface diameters ($d_s$), and the Ouzia et al. 2019 "needle model" roughness factor.
• configuration.py: Manages dynamic environment loading, ensuring local paths and material databases are resolved correctly across different user systems.
• utils.py: Support functions, featuring a standardized myplot utility for scientific visualization.

config/ User settings

• chemistry_database.ini: A central ledger for molar masses, densities, and enthalpies of formation ($J/mol$).
• physical_properties.py: Defines material-specific constants and links to raw PSD data files.
• paths.py: A multi-user path handler that automatically detects the local environment (e.g., ownCloud vs polybox paths) based on the OS username.
• user_functions.py: Placeholder for custom reader functions (e.g., read_psd_csv) to parse specific instrument outputs.
• colors.py: Centralized HEX codes and transparency maps for consistent plotting across different water/cement ($w/c$) ratios.

---

Key Features

1. Thermodynamic Yield Analysis

The Hydration class converts raw heat flow into physical volume changes. Using the data in your chemistry_database.ini, it calculates:

• Enthalpy of reaction: $$\Delta H^0_{reaction} = \sum (n \cdot \Delta H^0_f){products} - \sum (n \cdot \Delta H^0_f){reactants}$$
• Phase evolution: Derives $\Delta V_s$ (solid volume change) and $\Delta V_{prod}$ (volume of products formed) per Joule of heat generated.

2. Advanced PSD Blending

The Blend class doesn't just average diameters; it computes the weighted Particle Size Distribution for the total system, providing:

• Characteristic metrics: $d_{10}, d_{50}, d_{90}$ and surface-weighted $d_s$.
• Needle Model: Computes the ratio between roughness factor and form factor ($\rho/F$).

3. Collaborative Configuration

The Config system is designed for lab groups. By using paths.py, multiple researchers can use the same git repo on different machines without constantly changing hardcoded file paths.

---

Installation

buildupp can be install with pip. We recommend installing it in a virtual environment.

python3.11 -m venv venv_name

source venv_name/bin/activate

pip install buildupp

buildupp can also be installed in editable mode by cloning the repository

git clone https://gitlab.ethz.ch/smec/software/buildupp

cd buildupp

pip install -e .

Usage

1. Configure your environment

Update config/paths.py to include your username and local data directories. Then, ensure your chemistry_database.ini includes the compounds relevant to your study.

2. Run an Analysis

You can use the Experiment class from experiment.py to analyze coupled calorimetry/rheometry data. Here's an example of creating an experiment object:

from buildupp.experiment import Experiment
from buildupp.config import Config

# Load configuration
config = Config(config_dir='./config')

# Define experiment inputs (can also use default)
exp_inputs = {
    'db_entry': config.systems_measured['opc'][0]['db_entry']
}

# Create the experiment object
experiment = Experiment(exp_inputs=exp_inputs, config=config)

# Plot experimental results (example)
exp.plot_GtildeDVproductsperVgrain(ax=ax, c=c.opc, type=type, label='PC')

Alternatively, you can directly use the default config from buildupp.PROJECT_ROOT

from buildupp import config, Experiment

# leveraging config
s = config.systems_measured
c = config.colors
desktop_path = config.desktop_directory

# generate figure
fig, ax = plt.subplots()
type = 'semilogy'

# plot all PC measurements
for i, e in enumerate(s.opc):
    exp = Experiment(e)
    if i == 0:
        exp.plot_GtildeDVproductsperSgrain(ax=ax, c=c.opc, type=type, label='PC')
    else:
        exp.plot_GtildeDVproductsperSgrain(ax=ax, c=c.opc, type=type)

Scientific Background

This tool implements the coupling:

$$ G'(t)=G'_0​⋅\tilde{G}(\Delta H(t)) $$

where the evolution of the storage modulus $G'$ is analyzed as a function of the chemical progress $\Delta H$, allowing to investigate the impact of hydration products on stiffness increase.

License

Copyright © 2024 ETH Zurich (Luca Michel)

buildupp is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

buildupp is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with buildupp. If not, see https://www.gnu.org/licenses/.