Metadata-Version: 2.4
Name: buildupp
Version: 0.0.6
Summary: Investigate structural build-up at rest in cementitious systems
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pranzo==0.1.2
Requires-Dist: ipython==8.29.0
Requires-Dist: ipympl==0.9.4
Requires-Dist: ipywidgets==8.1.5
Dynamic: license-file

# 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](https://www.sciencedirect.com/science/article/pii/S0008884624002461), [Michel et al. 2025](https://ceramics.onlinelibrary.wiley.com/doi/10.1111/jace.70271)). 

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"](https://www.sciencedirect.com/science/article/pii/S0008884617305173) 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.

```bash
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
```bash
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:

```python
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

```python
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 &copy; 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/>.
