Metadata-Version: 2.4
Name: ACBICI
Version: 2.3.0
Summary: A Configurable BayesIan Calibration and Inference package
Author: Christina Schenk, Ignacio Romero
License: BSD-3-Clause License
        
        Copyright (c) 2025, Fundación IMDEA Materiales (IMDEA Materials Institute), Getafe, Madrid, Spain and Universidad Politécnica de Madrid (UPM), Madrid, Spain
        
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://gitlab.com/schenkch/ACBICI
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: pyDOE
Requires-Dist: emcee
Requires-Dist: h5py
Requires-Dist: corner
Requires-Dist: pyvbmc
Requires-Dist: tqdm
Requires-Dist: sphinx
Requires-Dist: sphinx-rtd-theme
Requires-Dist: sphinx-math-dollar
Requires-Dist: seaborn
Requires-Dist: SALib
Requires-Dist: pocomc
Dynamic: license-file

# <img alt="ACBICI" src="branding/ACBICI_Logo.svg" height="80">

[![License](https://img.shields.io/gitlab/license/schenkch/ACBICI?cacheSeconds=300)](https://gitlab.com/schenkch/ACBICI/-/blob/master/LICENSE)
[![Last Commit](https://img.shields.io/gitlab/last-commit/schenkch/ACBICI)](https://gitlab.com/schenkch/ACBICI/)
[![Documentation Status](https://readthedocs.org/projects/acbici/badge/?version=latest)](https://acbici.readthedocs.io/en/latest/py-modindex.html)

ACBICI (A Configurable BayesIan Calibration and Inference package) is a Python package designed to calibrate models including uncertainty estimates.

- **Documentation:** - https://acbici.readthedocs.io / Alternatively can be compiled following the instructions in docs/ReadmeDoc.txt file.  
- **Examples and Tutorials** - https://gitlab.com/schenkch/acbici/tree/master/examples
- **Source code:** - https://gitlab.com/schenkch/acbici/tree/master/src/ACBICI
- **Bug reports:** - https://gitlab.com/schenkch/acbici/issues


It has the following functionality:
 - Bayesian calibration
 - provide distribution for the model parameters
 - estimate aleatoric and epistemic uncertainty
 - Gaussian process surrogate models for faster predictions
 - visualization of results

<br>



## Installation
    Before installing ACBICI, you need to install make, git and one of the tested Python versions (3.9, 3.12, 3.13, 3.14).

    Then, if using Python for other purposes than ACBICI, it is recommended to use a virtual environment, you can create one for example via:
    - python3 -m venv acbici_env
    or:
    - virtualenv acbici_env
    Then activate the virtual environment by:
    - source acbici_env/bin/activate

    Upgrade packaging tools (recommended):
    pip install --upgrade pip setuptools wheel

    or with Anaconda (Windows) in the Anaconda prompt to create a virtual environment:
    - conda create -n myenv python=3.14
    Then to activate it:
    - conda activate myenv

    Next you can install ACBICI in this virtual environment:
    Either:
    Go to the folder where you want to install it via: cd "installation_directory"
    Clone and install the repo into that folder in the following way:
    - git clone https://gitlab.com/schenkch/ACBICI.git
    - cd ACBICI
    - pip install -e .
    Or:
    Install as an already built pip package via:
    - git clone https://gitlab.com/schenkch/ACBICI.git 
    - pip install ACBICI




### Examples and Tutorials

The example problems are in the examples subfolder at https://gitlab.com/schenkch/acbici/tree/master/examples.

    To run all the examples and test their correctness, open a terminal and change into the `examples` directory of the downloaded repository:
    cd examples

    Execute the following command:
    make

This will trigger the build process defined in the Makefile and run all the example problems within the folder.
This may take some time but if everything is set up correctly and all dependencies are satisfied, you should see output indicating whether each example has passed or failed.
In addition, each example subfolder contains a make file for automatic clean up of old results.

### Automatic MCMC continuation and restart

All Type A, B, C, and D calibrators can continue one MCMC chain until it
converges or a user-selected maximum is reached. The chain is considered
converged when, for every parameter, the post-burn chain is at least 50 times
its autocorrelation time and the split-Rhat of every parameter is below 1.01.

Automatic continuation is opt-in: existing calls that specify only `nsteps`
still run exactly that many steps and stop. Supply `next_steps`, `max_steps`,
or `restart=True` to enable continuation, for example:

```python
calibrator.calibrate(method="mcmc", nsteps=5000, next_steps=10000, max_steps=100000)
```

If a saved chain reaches its cumulative maximum before convergence, continue it
with a larger cumulative limit:

```python
calibrator.calibrate(method="mcmc", max_steps=200000, restart=True)
```

The chain is saved to disk (this requires `h5py`) only when `next_steps`,
`max_steps`, or `restart=True` is given. A completed run without continuation, for
example one that did not converge, can still be continued with `restart=True`: ACBICI
then starts from the last walker positions in `samples.npy`, but cannot check that
the model, data and settings are the same as in the original run.
For long runs, enabling continuation is recommended: the chain is saved after every
step and can be restarted even after a crash. For a single batch, set `max_steps`
equal to `nsteps`, e.g. `calibrate(nsteps=20000, max_steps=20000)`.

Final results combine all post-burn batches and restarts, burn-in remains fixed from
the initial run, and ACBICI prints important progress to both the terminal and
the same `acbici.log` file. The scripts `typeA_restart.py` and `typeD_restart.py`
in `examples/example0` show a first run and a restart (`python typeA_restart.py restart`).

SMC runs (`method="smc"`) save their state after every iteration and can also be
restarted, either to continue a finished run to a larger `nsamples` or after a crash:

```python
calibrator.calibrate(method="smc", nsamples=8000, restart=True)
```

The script `typeB_restart_smc.py` in `examples/example0` shows this for SMC.

### Quiet mode

By default, ACBICI prints progress and warnings to the terminal. To run a calibration
without any terminal output, for example in batch jobs, call

```python
calibrator.setVerbose(False)
```

before `calibrate`. Then `calibrate`, `plot` and `identifiabilityAnalysis` print nothing,
while `acbici.log` is written as usual and errors still stop the program.



## License

BSD-3



## Authors

    - Christina Schenk - IMDEA Materials Institute
    - Ignacio Romero - UPM, IMDEA Materials Institute


## Acknowledgements

    - Yufei Liu - IMDEA Materials Institute
    - Ross Cockcroft - Queens University Belfast



## Please cite
<br>

    - https://gitlab.com/schenkch/ACBICI.git
    - Schenk, C., Romero, I. A Framework for the Bayesian Calibration of Complex and Data-Scarce Models in Applied Sciences. Arch Computat Methods Eng (2026). https://doi.org/10.1007/s11831-026-10665-w
    - Preprint here: C. Schenk, I. Romero (2026): A Framework for the Bayesian Calibration of Complex and Data-Scarce Models in Applied Sciences, arXiv, https://arxiv.org/abs/2601.22890
