diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..6a14a9f
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,198 @@
+# HECSS - GitHub Copilot Instructions
+
+## Project Overview
+
+HECSS (High Efficiency Configuration Space Sampler) is a Python library for Markov chain Monte Carlo configuration space sampling using the Metropolis-Hastings algorithm. It provides an efficient alternative to molecular dynamics simulations for creating thermal equilibrium representations of physical systems.
+
+**Primary Use Case**: Sampling thermodynamic distributions of crystal structures at various temperatures without expensive MD simulations.
+
+## Technology Stack
+
+- **Language**: Python 3.6+
+- **Development Framework**: nbdev (notebook-based development)
+- **Core Dependencies**:
+ - ASE (Atomic Simulation Environment) - structure manipulation and calculator interface
+ - VASP & LAMMPS - DFT and classical MD calculators
+ - NumPy, SciPy - numerical computing
+ - spglib - symmetry operations
+ - tqdm - progress bars
+ - matplotlib - visualization
+ - click - CLI interface
+
+## Development Workflow
+
+### Notebook-First Development
+
+**CRITICAL**: This project uses nbdev - all source code is generated from Jupyter notebooks.
+
+- **DO NOT** edit Python files in `hecss/` directory directly (they are auto-generated)
+- **ALWAYS** edit the corresponding `.ipynb` notebook files in the root directory
+- Files have header comments indicating which notebook generates them (e.g., `# AUTOGENERATED! DO NOT EDIT! File to edit: 11_core.ipynb`)
+
+### Notebook to Module Mapping
+
+- `11_core.ipynb` → `hecss/core.py` (main HECSS sampler logic)
+- `12_monitor.ipynb` → `hecss/monitor.py` (monitoring and visualization)
+- `02_CLI.ipynb` → `hecss/cli.py` (command-line interface)
+- `00_Background.ipynb`, `00_Setup.ipynb` → documentation
+- `01_LAMMPS_Tutorial.ipynb`, `01_VASP_Tutorial.ipynb` → tutorials
+
+### Build Commands
+
+```bash
+# Build library from notebooks
+make hecss
+# or
+nbdev_build_lib
+
+# Build documentation
+make docs
+# or
+nbdev_build_docs
+
+# Run tests
+make test
+# or
+nbdev_test_nbs
+
+# Run tests with specific flags
+make test_asap # for ASAP3/OpenKIM tests
+make test_vasp # for VASP tests
+```
+
+## Code Style & Conventions
+
+### Python Style
+
+- Follow standard Python conventions (PEP 8)
+- Use type hints where appropriate
+- Preserve existing code structure and formatting
+- Use NumPy-style docstrings
+
+### Naming Conventions
+
+- Functions: `snake_case`
+- Classes: `PascalCase` (e.g., `HECSS_Sampler`, `HECSS`)
+- Constants: `UPPER_CASE`
+- Private functions: prefix with `_`
+
+### Physics & Scientific Computing
+
+- Use ASE units (`ase.units`) for physical quantities
+- Temperature in Kelvin
+- Energy in eV (electron volts)
+- Forces in eV/Angstrom
+- Use `un` as alias for `ase.units` (existing convention)
+- Preserve scientific notation and physical constants
+
+### Key Abstractions
+
+- **HECSS**: Main user-facing class for running sampling
+- **HECSS_Sampler**: Lower-level sampler implementation
+- Structures are ASE `Atoms` objects
+- Calculators follow ASE calculator interface
+- Samples are tuples: `(n, i, displacement, forces, energy)`
+
+## Testing
+
+- Tests are embedded in notebooks with `#slow`, `#vasp`, `#asap`, `#interactive` flags
+- Use `nbdev_test_nbs` with appropriate flags
+- Tests require external calculators (VASP, LAMMPS/ASAP3) - not all tests may run in CI
+- Focus on testing sampling convergence and statistical properties
+
+## Documentation
+
+- Generated automatically from notebooks using nbdev
+- Hosted at: https://jochym.gitlab.io/hecss/
+- API documentation is in notebook cells with `#export` directive
+- Examples and tutorials are in dedicated notebook files
+
+## Repository Structure
+
+```
+.
+├── .github/ # GitHub configuration
+├── hecss/ # Auto-generated Python package (DO NOT EDIT)
+│ ├── core.py # Main sampling logic
+│ ├── monitor.py # Monitoring and plotting
+│ └── cli.py # Command-line tools
+├── *.ipynb # Source notebooks (EDIT THESE)
+├── docs/ # Generated documentation
+├── example/ # Example calculations and data
+├── data/ # Data files
+├── settings.ini # Project configuration
+├── setup.py # Package setup
+└── Makefile # Build automation
+```
+
+## Contributing Guidelines
+
+### Making Changes
+
+1. Edit the appropriate `.ipynb` notebook file, not the generated `.py` files
+2. Run `make hecss` to regenerate Python modules
+3. Run `make test` (or targeted tests) to verify changes
+4. Run `make docs` to update documentation
+5. Keep PRs focused on a single feature or fix
+6. Do not mix style changes with functional changes
+
+### PR Requirements
+
+- Include tests that demonstrate the fix or feature
+- Ensure tests pass
+- Update documentation in notebooks if needed
+- Clear description of problem and solution
+- Reference related issue numbers
+
+## Special Considerations
+
+### Calculator Integration
+
+- VASP calculator requires proper POTCAR files and working VASP installation
+- LAMMPS/ASAP3 calculators need OpenKIM models
+- Not all calculator tests can run in standard CI environments
+
+### Performance
+
+- HECSS is designed for efficiency - avoid unnecessary calculations
+- Sampling can be long-running - use progress bars (tqdm)
+- Support for parallel sampling may be added in future
+
+### File Formats
+
+- Supports ALAMODE DFSET format for displacement-force data
+- Uses standard ASE structure formats
+- Configuration files use Python ConfigParser format (settings.ini)
+
+## Common Tasks
+
+### Adding a New Feature to Core Sampling
+
+1. Edit `11_core.ipynb`
+2. Add function/class with `#export` directive
+3. Add to `__all__` list
+4. Include docstring and example
+5. Run `make hecss && make test`
+
+### Adding a CLI Command
+
+1. Edit `02_CLI.ipynb`
+2. Use `@click.command()` decorator
+3. Add to `console_scripts` in `settings.ini`
+4. Run `make hecss`
+
+### Updating Documentation
+
+1. Edit the relevant tutorial or documentation notebook
+2. Run `make docs` to regenerate
+3. Check output in `docs/` directory
+
+## License
+
+GPL v3 or later - ensure any contributions are compatible with this license.
+
+## Contact
+
+- Author: Paweł T. Jochym (pawel.jochym@ifj.edu.pl)
+- Primary Repository: https://gitlab.com/jochym/hecss
+- Mirror: https://github.com/jochym/hecss
diff --git a/Makefile b/Makefile
index 70f58bc..d4a7e98 100644
--- a/Makefile
+++ b/Makefile
@@ -23,7 +23,7 @@ test_vasp:
nbdev_test_nbs --flags vasp
release: pypi # conda_release
- nbdev_bump_version --part 2
+ nbdev_bump_version --part 3
conda_meta:
fastrelease_conda_package --do_build false
@@ -36,7 +36,7 @@ conda_release: conda_meta
conda mambabuild --python 3.8 conda/hecss
pypi: dist
- twine upload --repository test_hecss dist/*
+ twine upload --repository hecss dist/*
dist: clean
python setup.py sdist bdist_wheel
diff --git a/README.md b/README.md
index a484099..93199e3 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,9 @@
[](https://anaconda.org/conda-forge/hecss)
[](https://anaconda.org/jochym/hecss)
-HECSS is a Markow chain Monte-Carlo, configuration space sampler using Metropolis-Hastings algorithm for probablity distribution sampling. It provides an alternative way to create representations of systems at thermal equilibrium without running a very expensive molecular dynamics simulation. The theoretical foundation of the code are presented in the section [Background](https://jochym.gitlab.io/hecss/Background) in the [Documentation](https://jochym.gitlab.io/hecss/). More detailed examples are included in the [LAMMPS](https://jochym.gitlab.io/hecss/LAMMPS_Tutorial) and [VASP](https://jochym.gitlab.io/hecss/VASP_Tutorial) tutorials.
+HECSS is a Markow chain Monte-Carlo, configuration space sampler using Metropolis-Hastings algorithm for probablity distribution sampling. It provides an alternative way to create representations of systems at thermal equilibrium without running a very expensive molecular dynamics simulation. The theoretical foundation of the code are presented in [SciPost Phys. 10, 129 (2021)](https://scipost.org/SciPostPhys.10.6.129) (short excerpt in [Background](https://jochym.gitlab.io/hecss/Background) in the [Documentation](https://jochym.gitlab.io/hecss/)). More detailed examples are included in the [LAMMPS](https://jochym.gitlab.io/hecss/LAMMPS_Tutorial) and [VASP](https://jochym.gitlab.io/hecss/VASP_Tutorial) tutorials.
+
+If you use this software in published research please cite the above paper ([BibTeX](https://gitlab.com/jochym/hecss/-/raw/master/scipost.bib)) in your publication.
## A very short example
diff --git a/docs/images/output_9_0.png b/docs/images/output_9_0.png
index 21b3ab8..d034ff2 100644
Binary files a/docs/images/output_9_0.png and b/docs/images/output_9_0.png differ
diff --git a/docs/index.html b/docs/index.html
index c3375fc..f98b4a6 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -36,7 +36,8 @@
HECSS is a Markow chain Monte-Carlo, configuration space sampler using Metropolis-Hastings algorithm for probablity distribution sampling. It provides an alternative way to create representations of systems at thermal equilibrium without running a very expensive molecular dynamics simulation. The theoretical foundation of the code are presented in the section Background in the Documentation. More detailed examples are included in the LAMMPS and VASP tutorials.
+HECSS is a Markow chain Monte-Carlo, configuration space sampler using Metropolis-Hastings algorithm for probablity distribution sampling. It provides an alternative way to create representations of systems at thermal equilibrium without running a very expensive molecular dynamics simulation. The theoretical foundation of the code are presented in SciPost Phys. 10, 129 (2021) (short excerpt in Background in the Documentation). More detailed examples are included in the LAMMPS and VASP tutorials.
+If you use this software in published research please cite the above paper (BibTeX) in your publication.
@@ -156,7 +157,7 @@