Metadata-Version: 2.5
Name: molass
Version: 1.0.8
Summary: Matrix Optimization with Low-rank factorization for Automated analysis of SEC-SAXS
Project-URL: Repository, https://github.com/biosaxs-dev/molass-library
Author: Masatsuyo Takahashi, Nobutaka Shimizu
Maintainer: Masatsuyo Takahashi, Nobutaka Shimizu
License: GNU General Public License v3.0
License-File: LICENSE.txt
Keywords: SEC-SAXS
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.15,>=3.12
Requires-Dist: cma
Requires-Dist: ipykernel
Requires-Dist: ipywidgets
Requires-Dist: learnsaxs
Requires-Dist: matplotlib
Requires-Dist: molass-legacy>=1.6.12
Requires-Dist: mrcfile
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: psutil
Requires-Dist: pybaselines>=1.2.0
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: seaborn
Requires-Dist: shapely
Requires-Dist: statsmodels
Requires-Dist: toml
Requires-Dist: tqdm
Provides-Extra: excel
Requires-Dist: pywin32; extra == 'excel'
Provides-Extra: testing
Requires-Dist: pytest; extra == 'testing'
Requires-Dist: pytest-cov; extra == 'testing'
Requires-Dist: pytest-env; extra == 'testing'
Requires-Dist: pytest-order; extra == 'testing'
Description-Content-Type: text/markdown

<h1 align="center"><a href="https://biosaxs-dev.github.io/molass-library"><img src="docs/_static/molass-title.png" width="300"></a></h1>

<p align="center">
<a href="https://doi.org/10.21105/joss.10403"><img src="https://joss.theoj.org/papers/10.21105/joss.10403/status.svg" alt="DOI"></a>
</p>

Molass Library is a rewrite of [MOLASS](https://pfwww.kek.jp/saxs/MOLASSE.html), a tool for the analysis of SEC-SAXS experiment data currently hosted at the Japanese synchrotron radiation facilities, [Photon Factory](https://pfwww.kek.jp/saxs/MOLASSE.html) and [SPring-8](https://www.riken.jp/en/research/labs/rsc/rd_ts_sra/life_sci_res_infrastruct/index.html)

## Tested Platforms

Continuous integration tests run on:
- Python 3.12, 3.13, 3.14 on Ubuntu (latest)
- Python 3.12, 3.13, 3.14 on Windows (latest)

## Installation

**Requirements:** Python 3.12, 3.13, or 3.14

**Linux (Ubuntu/Debian) prerequisites:**

Before installing on Linux, ensure system build tools are available (needed to compile C extensions such as `ultranest`):

```
sudo apt install build-essential python3-dev
```

To install this package, use pip as follows:

```
pip install -U molass
pip install molass_data  # Sample datasets for tutorials and testing
```

For development (requires `molass-legacy` as a sibling directory):

```
git clone https://github.com/biosaxs-dev/molass-library
git clone https://github.com/biosaxs-dev/molass-legacy
cd molass-library
pip install -e ".[testing]"
pip install molass_data
```

## Quick Start

For a hands-on introduction, see the tutorial's [Quick Start](https://biosaxs-dev.github.io/molass-tutorial/quick-start) section, or run the corresponding test file:

```python
pytest tests/tutorial/01-quick_start.py -v
```

> **Note:** Running tests requires the development install. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.

The [molass-beginner](https://github.com/biosaxs-dev/molass-beginner) repository provides an interactive onboarding experience in VS Code Agent mode.

## Documentation

- **Beginner Onboarding:** https://github.com/biosaxs-dev/molass-beginner — Agent-mode first-run guide, for first-time users
- **GUI:** https://github.com/biosaxs-dev/molass-gui — Tkinter desktop app, for users who prefer a guided point-and-click workflow over notebooks
- **Tutorial:** https://biosaxs-dev.github.io/molass-tutorial — practical usage, for beginners
- **Essence:** https://biosaxs-dev.github.io/molass-essence — theory, for researchers
- **Technical Report:** https://biosaxs-dev.github.io/molass-technical — technical details, for advanced users
- **Reference:** https://biosaxs-dev.github.io/molass-library — function reference, for coding
- **Legacy Repository:** https://github.com/biosaxs-dev/molass-legacy — legacy code

## Citation

If you use Molass Library in your research, please cite the JOSS paper:

> Takahashi, M., & Shimizu, N. (2026). Molass Library: A Python Package for SEC-SAXS Data Analysis. *Journal of Open Source Software*, 11(124), 10403. https://doi.org/10.21105/joss.10403

```bibtex
@article{Takahashi2026,
  doi = {10.21105/joss.10403},
  url = {https://doi.org/10.21105/joss.10403},
  year = {2026},
  publisher = {The Open Journal},
  volume = {11},
  number = {124},
  pages = {10403},
  author = {Masatsuyo Takahashi and Nobutaka Shimizu},
  title = {Molass Library: A Python Package for SEC-SAXS Data Analysis},
  journal = {Journal of Open Source Software}
}
```

See also [`CITATION.cff`](CITATION.cff) for citing the software itself.

## Community

To join the community, see:

- **Handbook:** https://biosaxs-dev.github.io/molass-develop — maintenance, for developers
- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute
- **Support:** [GitHub Issues](https://github.com/biosaxs-dev/molass-library/issues) — questions, bugs, and feature requests

Especially for testing, see the first two sections in
- **Testing:** https://biosaxs-dev.github.io/molass-develop/chapters/06/testing.html

## Copilot Usage

Context is auto-loaded from `.github/copilot-instructions.md` when using GitHub Copilot in Agent mode ([AI Context Standard](https://github.com/freesemt/ai-context-standard)).

For behavioral rules and user-type guidance, see [`Copilot/copilot-guidelines.md`](https://github.com/biosaxs-dev/molass-library/blob/main/Copilot/copilot-guidelines.md).

## Optional Features

**Excel reporting (Windows only):**

If you want to use Excel reporting features (Windows only) for backward compatibility, install with the `excel` extra:

```
pip install -U molass[excel]
```

> **Note:** The `excel` extra installs `pywin32`, which is required for Excel reporting and only works on Windows.

