jochym · Copilot · Nov 25, 2021 · May 17, 2022 · May 17, 2022 · May 17, 2022
diff --git a/.github/copilot-instructions.md 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
@@ -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
@@ -8,7 +8,9 @@
 [![Downloads Badge](https://anaconda.org/conda-forge/hecss/badges/downloads.svg)](https://anaconda.org/conda-forge/hecss)
 [![License Badge](https://anaconda.org/jochym/hecss/badges/license.svg)](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
diff --git a/docs/index.html b/docs/index.html
diff --git a/hecss/__init__.py b/hecss/__init__.py
@@ -1 +1 @@
-__version__ = "0.4.5"
+__version__ = "0.5.0.2"
diff --git a/index.ipynb b/index.ipynb
diff --git a/settings.ini b/settings.ini
@@ -7,15 +7,15 @@ keywords = physics temperature configurations
 author = Paweł T. Jochym
 author_email = pawel.jochym@ifj.edu.pl
 copyright = Paweł T. Jochym
-branch = devel
-version = 0.4.5
+branch = master
+version = 0.5.0.2
 min_python = 3.6
 audience = Science/Research
 language = English
 custom_sidebar = False
 license = GPL3
 status = 4
-requirements = ase spglib tqdm click matplotlib numpy scipy
+requirements = ase spglib tqdm click matplotlib numpy scipy ipython
 console_scripts = hecss_sampler=hecss.cli:hecss_sampler plot_stats=hecss.cli:plot_stats plot_bands=hecss.cli:plot_bands calculate_xscale=hecss.cli:calculate_xscale
 nbs_path = .
 doc_path = docs