Metadata-Version: 2.4
Name: hybrid-perovskite-studio
Version: 0.2.0
Summary: Workspace-oriented Streamlit toolkit for hybrid perovskite modeling, analysis, and visualization.
Author: Rayan Chakraborty
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/rayanc72/hybrid-perovskite-studio
Project-URL: Documentation, https://github.com/rayanc72/hybrid-perovskite-studio/tree/main/docs
Project-URL: Repository, https://github.com/rayanc72/hybrid-perovskite-studio
Project-URL: Issues, https://github.com/rayanc72/hybrid-perovskite-studio/issues
Keywords: hybrid perovskites,materials science,structure analysis,streamlit,electronic structure,molecular dynamics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit>=1.33
Provides-Extra: core
Requires-Dist: ase; extra == "core"
Requires-Dist: kaleido; extra == "core"
Requires-Dist: matplotlib; extra == "core"
Requires-Dist: natsort; extra == "core"
Requires-Dist: networkx; extra == "core"
Requires-Dist: numpy; extra == "core"
Requires-Dist: pandas; extra == "core"
Requires-Dist: pillow; extra == "core"
Requires-Dist: plotly; extra == "core"
Requires-Dist: pymatgen; extra == "core"
Requires-Dist: pyyaml; extra == "core"
Requires-Dist: requests; extra == "core"
Requires-Dist: scipy; extra == "core"
Requires-Dist: spglib; extra == "core"
Provides-Extra: md
Requires-Dist: MDAnalysis; extra == "md"
Requires-Dist: seaborn; extra == "md"
Provides-Extra: pdf
Requires-Dist: diffpy.pdffit2; extra == "pdf"
Requires-Dist: diffpy.structure; extra == "pdf"
Provides-Extra: viz
Requires-Dist: bokeh; extra == "viz"
Requires-Dist: colorcet; extra == "viz"
Requires-Dist: holoviews; extra == "viz"
Requires-Dist: mpld3; extra == "viz"
Requires-Dist: streamlit-bokeh-events; extra == "viz"
Requires-Dist: streamlit-extras; extra == "viz"
Requires-Dist: streamlit-ketcher; extra == "viz"
Requires-Dist: streamlit-lottie; extra == "viz"
Provides-Extra: auth
Requires-Dist: streamlit-authenticator; extra == "auth"
Provides-Extra: backend
Requires-Dist: fastapi; extra == "backend"
Requires-Dist: pydantic; extra == "backend"
Requires-Dist: uvicorn; extra == "backend"
Provides-Extra: full
Requires-Dist: ase; extra == "full"
Requires-Dist: bokeh; extra == "full"
Requires-Dist: colorcet; extra == "full"
Requires-Dist: fastapi; extra == "full"
Requires-Dist: holoviews; extra == "full"
Requires-Dist: kaleido; extra == "full"
Requires-Dist: matplotlib; extra == "full"
Requires-Dist: MDAnalysis; extra == "full"
Requires-Dist: mpld3; extra == "full"
Requires-Dist: natsort; extra == "full"
Requires-Dist: networkx; extra == "full"
Requires-Dist: numpy; extra == "full"
Requires-Dist: pandas; extra == "full"
Requires-Dist: pillow; extra == "full"
Requires-Dist: plotly; extra == "full"
Requires-Dist: pydantic; extra == "full"
Requires-Dist: pymatgen; extra == "full"
Requires-Dist: pyyaml; extra == "full"
Requires-Dist: requests; extra == "full"
Requires-Dist: scipy; extra == "full"
Requires-Dist: seaborn; extra == "full"
Requires-Dist: spglib; extra == "full"
Requires-Dist: streamlit-authenticator; extra == "full"
Requires-Dist: streamlit-bokeh-events; extra == "full"
Requires-Dist: streamlit-extras; extra == "full"
Requires-Dist: streamlit-ketcher; extra == "full"
Requires-Dist: streamlit-lottie; extra == "full"
Requires-Dist: uvicorn; extra == "full"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Dynamic: license-file

# Hybrid Perovskite Studio

Hybrid perovskites are a highly tunable family of functional semiconductors with broad relevance across materials science,
chemistry, and condensed-matter physics. Their hybrid organic-inorganic character makes them especially valuable for 
studying structure-property relationships through systematic changes in composition, molecular orientation, and 
lattice symmetry. At the same time, that same hybrid character makes them difficult to analyze with many conventional
structural-chemistry workflows, since the organic and inorganic sublattices often need to be treated differently.

Hybrid Perovskite Studio (HPS) is a workspace-oriented environment, built on top of Streamlit, designed to support analysis and modelling of hybrid organic-inorganic materials. Although it focuses upon hybrid perovskites (following its development purpose), the tools are equally applicable to other materials classes, including typical organic or inorganic compositions.
Its Structure Workspace focuses on tools for parsing, analyzing, and transforming crystal structures while explicitly distinguishing 
between molecular and inorganic building blocks. Starting from experimental or simulated structures, users can inspect symmetry, molecular connectivity, bond lengths, bond angles, distortion metrics,
anisotropic displacement information, pair distribution functions, and polarization-related quantities. 
The same workspace also supports structure editing and modelling operations, including molecule-specific rotations, reflections, translations, deletions, and interpolation-based transformations.

Beyond structure chemistry, HPS also provides tools for analyzing computational outputs. The Electronic Workspace is currently tailored especially to FHI-aims-style inputs and outputs, and includes functionality for plotting band structures, spin textures, densities of states, polarization-related quantities, absorption spectra, and Brillouin-zone map. The Dynamics Workspace extends the analysis to time-dependent simulation data, with tools for extracting trajectory-based structural metrics and monitoring how distortions and related descriptors evolve over time. A Utilities Workspace collects supporting tools for plotting and lightweight custom scripting.

HPS is an active research software project and is still evolving. 
It grew out of a longer collection of notebook-based and script-based workflows developed for hybrid-perovskite research, 
and is gradually being consolidated into a more structured, reusable application. While the codebase is already useful for day-to-day analysis, some workflows remain under active refinement and 
edge cases may still appear. The broader goal is to continue expanding HPS into a flexible and maintainable platform for 
hybrid perovskite modelling, analysis, and visualization.

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install hybrid-perovskite-studio
hps
```

The base package provides the launcher and dependency guidance. To install the functional application stack directly:

```bash
pip install "hybrid-perovskite-studio[full]"
```

## Run

```bash
hps
```

For local development:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[full,dev,docs]"
hps
```

To run the local backend service directly:

```bash
source .venv/bin/activate
hps-backend --host 127.0.0.1 --port 8765
```

To run the current backend-focused regression suite:

```bash
source .venv/bin/activate
python -m pytest tests/test_backend_store.py tests/test_backend_api.py tests/test_backend_phase3_workflows.py tests/test_core_workflows.py -q
```

## Guided Examples

Published, provenance-aware example projects are included in the package:

```bash
hps-examples list
hps-examples build structure
hps-examples build electronic
hps-examples build dynamics
```

Each generated ZIP includes a guided workflow, source citation, expected numerical
results, provenance notes, and checksum-validated inputs.

## Docs

- [Getting Started](docs/user-guide/getting-started.md)
- [Feature Map](docs/feature-map.md)
- [Workspace Guides](docs/index.md)
- [Backend Modernization](docs/reference/backend-modernization.md)
- [Guided Examples](docs/user-guide/guided-examples.md)
- [Development TODO](TODO.md)

To preview the documentation locally:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-docs.txt
mkdocs serve
```

To build the static docs site locally:

```bash
mkdocs build
```

## Gallery

![Landing Page](docs/images/screenshots/landing-page.png)

![Structure Workspace](docs/images/screenshots/structure-workspace.png)

![Band Structure Studio](docs/images/screenshots/band-structure-studio.png)

![Dynamics Workspace](docs/images/screenshots/dynamics-workspace.png)

## Notes

- PyPI/package entrypoint: `hps`
- Local backend entrypoint: `hps-backend`
- Main entrypoint: `streamlit run src/hps/app.py`
- Runtime files belong under `tmp/` and `output/`
- Navigation is defined in `src/hps/ui/navigation.py`
- The Streamlit app now attempts to auto-start a local backend service for cached/background workflows
- Backend-migrated workflows include structure context, symmetry sweep, PXRD/PDF simulation, PDOS/band/spin preprocessing, MD output parsing, and trajectory archive validation
