FUCrIMODo

Find Unknown Crystals by Inversion of ML Optimized Descriptors

---

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. 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
• Install
• Tutorials
  • Use fucrimodo CLI
  • Use fucrimodo as a library
• Documentation
• Roadmap
• Contact
• Authors and acknowledgment
• License
• Citation

Requirements

• Python 3.12 or later
• Numpy (Handle arrays and calculations.)
• Pandas (Handle data.)
• DEAP (GA framework.)
• ASE-GA (Atomic structure GA Framework.)
• Atomic Simulation Environment (ASE)(Atomic structure framework.)
• PyXtal (Atomic structure sampling.)
• MatID (Perform Atomic symmetry operations.)
• DScribe (Descriptor calculator.)
• Click (CLI backend.)
• Matplotlib (2D Plotting.)

Install

To install the latest release:

pip install fucrimodo

Or to install the development version:

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

For more detailed instructions, including setup with uv and conda, please refer to the documentation.

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:

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. Also refer to the documentation for more details.

Documentation

The documentation is hosted at read the docs. It includes additional tutorials and documents the API of fucrimodo.

To build it yourself, first install the dependencies:

pip install ".[docs]"

Now an HTML version of the docs can be generated:

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.:

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)

@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

  (\{\             .               ,@@@@                
  { { \ ,~,  ^  .     ~        __ _ ),\\(\   _,::;
   {   \|`) <*>   +  o------o  .)\)\\_(((\),:::::;
  { {  /(\  /~      /|     /|   `\`._,)))))::::::`,
   {/{/; ,\/       o------o |     `.__/(((:::::::' 
      [[ '         | |    | |        \  (`:::::::.
       \` \        | o----+-o         @**\ `:::::; 
       (/ \\       |/mlp  |/         /    \ `::'    
ejm    `)  `\      o------o         '*~*~*~`         
                                      | //
                                      \ \\
                                       `.\\
                                         \((
                                          ` ` hjw

(I will be a human, too!~Ponyo)