Metadata-Version: 2.4
Name: fucrimodo
Version: 1.0.0
Summary: Find Unknown Crystals by Inversion of ML Optimized Descriptors
Author-email: Louis Böhm <louis.boehm@gmx.de>, Martin Kuban <kuban@physik.hu-berlin.de>
Maintainer-email: Louis Böhm <louis.boehm@gmx.de>
Project-URL: Repository, https://github.com/OHANAN1/fucrimodo
Project-URL: Documentation, https://fucrimodo.readthedocs.io
Keywords: tools,fucrimodo,Material Science,Descriptor,SOAP
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.2.3
Requires-Dist: ase>=3.25.0
Requires-Dist: ase-ga>=1.0.3
Requires-Dist: matid>=2.1.5
Requires-Dist: matplotlib>=3.9.2
Requires-Dist: deap>=1.4.1
Requires-Dist: pyxtal>=1.0.6
Requires-Dist: dscribe>=2.1.1
Requires-Dist: click>=8.4.2
Provides-Extra: docs
Requires-Dist: sphinx==9.1.0; extra == "docs"
Requires-Dist: sphinx_rtd_theme==3.1.0; extra == "docs"
Requires-Dist: nbsphinx==0.9.8; extra == "docs"
Requires-Dist: ipykernel>=7.3.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest==9.1.1; extra == "test"
Provides-Extra: dev
Requires-Dist: isort>=8.0.1; extra == "dev"
Requires-Dist: black>=26.5.1; extra == "dev"
Requires-Dist: pyright>=1.1.411; extra == "dev"
Dynamic: license-file

<div align="center">

# FUCrIMODo

<img src="./res/Fujimoto_legal.png" width="200" height="200" alt="Fujimoto from the movie Ponyo">

**F**ind **U**nknown **C**rystals by **I**nversion of **M**L **O**ptimized **D**escriptors

---

</div>

**FUCrIMODo** is a scientific framework for recovering atomic structures from
machine-learning descriptors. It is built around a novel multi-stage Genetic
Algorithm (GA). The method and program are introduced in [this
publication](https://arxiv.org/abs/2608.23381).  FUCrIMODo comes with an
inversion algorithm for the global SOAP descriptor out of the box, and more
descriptors are on the way or can be added by you!

## Table of Contents

- [Requirements](#requirements)
- [Install](#install)
- [Tutorials](#tutorials)
  - [Use fucrimodo CLI](#use-fucrimodo-cli)
  - [Use fucrimodo as a library](#use-fucrimodo-as-a-library)
- [Documentation](#documentation)
- [Roadmap](#roadmap)
- [Contact](#contact)
- [Authors and acknowledgment](#authors-and-acknowledgment)
- [License](#license)
- [Citation](#citation)

## Requirements

- Python 3.12 or later
- [Numpy](https://numpy.org/doc/stable/) (Handle arrays and calculations.)
- [Pandas](https://pandas.pydata.org/docs/index.html) (Handle data.)
- [DEAP](https://deap.readthedocs.io/en/master/) (GA framework.)
- [ASE-GA](https://dtu-energy.github.io/ase-ga/) (Atomic structure GA Framework.)
- [Atomic Simulation Environment (ASE)](https://docs.ase-lib.org/index.html)(Atomic structure framework.)
- [PyXtal](https://pyxtal.readthedocs.io/en/latest/index.html) (Atomic structure sampling.)
- [MatID](https://singroup.github.io/matid/index.html#) (Perform Atomic symmetry operations.)
- [DScribe](https://singroup.github.io/dscribe/2.1.x/#) (Descriptor calculator.)
- [Click](https://click.palletsprojects.com/en/stable/) (CLI backend.)
- [Matplotlib](https://matplotlib.org/) (2D Plotting.)

## Install

To install the latest release:

``` bash
pip install fucrimodo
```

Or to install the development version:

``` bash
pip install git+git@github.com:OHANAN1/fucrimodo.git
```

For more detailed instructions, including setup with `uv` and `conda`, please refer to the [documentation](https://fucrimodo.readthedocs.io/en/latest/index.html).

## Tutorials

### Use fucrimodo CLI

To use fucrimodo as a cli you need to set up a `fucrimodo_lab`.  The
`fucrimodo_lab` is a human-readable database that allows you to manage 
configurations, data, analysis and more. To set it up, go to a desired
directory (ideally outside the library's git structure) and run:

``` bash
fucrimodo lab init
```

This creates a directory called fucrimodo_lab and sets up the required directory
structure. Example raw data is provided so you can perform test runs. Please set
it up and refer to the README.md file inside the lab for more info.

### Use fucrimodo as a library

To learn how to configure the CLI tool or use fucrimodo as a library, you can work through [this Jupyter notebook tutorial](tutorials/fucrimodo_as_library.ipynb). Also refer to the documentation for more details.

## Documentation

The documentation is hosted at [read the docs](https://fucrimodo.readthedocs.io/en/latest/index.html).
It includes additional tutorials and documents the API of fucrimodo.

To build it yourself, first install the dependencies:

``` bash
pip install ".[docs]"
```

Now an HTML version of the docs can be generated:

``` bash
cd docs/
make html
```

The docs will be generated at _build/html/ and can then be opened with the
browser of your choice. E.g.:

``` bash
qutebrowser _build/html/index.html
```


## Roadmap

- [ ] Implement and test additional descriptors types
- [ ] Implement new Stage types
    - [ ] `ParallelGAStage` (Run multiple GA stages parallel.)
    - [ ] `SwarmSearchStage` (Use a swarm search for the ideal descriptor.)
    - [ ] `GradientDescentStage` (Follow the descriptor gradients.)
- [ ] Improve current default run configuration for bigger structures
- [ ] Add a proper way to update `fucrimodo_lab` defaults without overwriting
      existing defaults.

## Contact

- GitHub issues: https://github.com/OHANAN1/fucrimodo/issues
- Email: louis.boehm@gmx.de

## Authors and acknowledgment

- Main Author: Louis Böhm
- Co-Author: Martin Kuban

## License

The program is licensed with the Apache 2.0 license.

## Citation

If you use this program in a scientific publication please add the following citation:
(This is the preprint)

``` bibtex
@article{FUCrIMODo_Boehm_2026,
  author = {Boehm, Louis and Kuban, Martin and Draxl, Claudia},
  eprint = {2608.23381v1},
  eprintclass = {cond-mat.mtrl-sci},
  eprinttype = {arxiv},
  title = {FUCrIMODo: structure recovery from atomistic descriptors via multi-stage genetic algorithms},
  month = {8},
  year = {2026},
  url = {http://arxiv.org/abs/2608.23381v1},
}
```

## Little Reward

As a reward that you read the complete README.md file you can now look at this
cute ASCII-Art. :D
```txt
  (\{\             .               ,@@@@                
  { { \ ,~,  ^  .     ~        __ _ ),\\(\   _,::;
   {   \|`) <*>   +  o------o  .)\)\\_(((\),:::::;
  { {  /(\  /~      /|     /|   `\`._,)))))::::::`,
   {/{/; ,\/       o------o |     `.__/(((:::::::' 
      [[ '         | |    | |        \  (`:::::::.
       \` \        | o----+-o         @**\ `:::::; 
       (/ \\       |/mlp  |/         /    \ `::'    
ejm    `)  `\      o------o         '*~*~*~`         
                                      | //
                                      \ \\
                                       `.\\
                                         \((
                                          ` ` hjw
```
(`I will be a human, too!`~Ponyo)



