MTCSP FAQs – Matlantis Corporation

This FAQ guide covers general questions about Matlantis CSP (MTCSP) as well as its two core search modes: Convex Hull Search and Derivative Structure Search.

General
- What are the key features of Matlantis CSP?
- What are the main capabilities?
- What is MTCSP Pro?
  - Are vacancies counted as a fourth element?
  - Are there any case studies for quaternary or higher systems?
- Which PFP calculation mode is used?
- How is the formation energy calculated?
  - Can the convergence criteria for relaxation calculations be modified?
  - Can I obtain single-point energy values instead of formation energy?
  - Can I obtain the energy distance from the convex hull?
- Can it handle molecular crystals?
- Can it search for structures that achieve specific desired property values?
- How can I resume a search from where it left off?
- How can I achieve a wider search space?
- How can I reduce search time? - Both modes
Convex Hull Search
- What is the typical workflow for a Convex Hull Search?
  - What is the recommended value for n_crystal_structures?
- How do I perform a constrained search? - For Convex Hull Search
- How can I reduce search time? - For Convex Hull Search
Derivative Structure Search
- What is the workflow for a Derivative Structure Search?
- How can I apply constraints to the generation of derivative structures?
- How can I reduce search time? - For Derivative Structure Search
References

Please also refer to the internal documentation within Matlantis.
About MTCSP

General

What are the key features of Matlantis CSP?

Comprehensive Exploration – Covers large search spaces including multi-element systems, variable compositions, and defect structures.
Traditional crystal structure prediction (CSP) typically requires fixed compositions. In contrast, MTCSP's Convex Hull Search explores a vast search space without fixing the number of atoms or chemical composition.
High-Speed Performance – Fast energy evaluation using PFP combined with Optuna-powered parallelization.
Conventional CSP relies on DFT calculations for energy evaluation, which can take anywhere from several hours to days per structure. MTCSP leverages high-speed energy evaluation via PFP and a parallel processing framework optimized for MTCSP using Optuna, making it possible to execute tens of thousands of trials within a practical timeframe.
High Efficiency – Builds large convex hulls with fewer trials using a genetic algorithm.
Thanks to a proprietary genetic algorithm designed specifically for convex hull construction, MTCSP achieves approximately 3 to 7 times higher search efficiency compared to random search methods.

Note: These features primarily apply to the Convex Hull Search.
Note 2: Optuna is an open-source hyperparameter optimization framework.

For more details on the methodology behind MTCSP, please refer to our paper:
Phys. Rev. Materials, 10, 063401 (2026)

What are the main features?

MTCSP offers two distinct search modes depending on your objective:

Convex Hull Search Explores the entire composition space using a proprietary genetic algorithm to construct phase diagrams (convex hulls). This mode is used when both the composition and crystal structure are unknown, and you want to discover combinations of stable structures and compositions.

Example: Searching for stable structures and compositions within the Sr-Ti-O (strontium, titanium, and oxygen) system.
Derivative Structure Search Explores derived structures by performing atomic substitutions or introducing vacancies, starting from a known prototype structure. This mode is used when you want to test partial substitutions or vacancies while maintaining the framework of the known structure.

Example: Searching for stable structures where the Co sites in LiCoO₂ are substituted with Ni or Mn.

What is MTCSP Pro?

MTCSP Pro is a paid upgrade that enables exploration of complex systems with four or more components. Systems with up to three components (ternary systems) are available to all users at no additional cost. Please contact your sales representative for pricing and license details.

How to determine the number of components (Ternary vs. Quaternary)
Here are examples to help you identify whether your target system is classified as a ternary or quaternary system:

Examples of Determining the Number of Components

Use the following examples to correctly determine how your system is classified:

Case / System Type	Example	Classification
Binary system with one element replaced by vacancies	Oxygen-deficient Ce-O system	Binary
Binary system with one element partially substituted	Mg-O system with Mg partially substituted by Zn: (Mg,Zn)O	Ternary
Binary system with one element partially substituted by two elements	Mg-O system with Mg partially substituted by Zn and Ni: (Mg,Zn,Ni)O	Quaternary
Ternary system with one element replaced by vacancies	Li-deficient Li-Co-O system	Ternary
Ternary system with one element partially substituted	Li-Co-O system with Co partially substituted by Ni: Li(Co, Ni)O₂	Quaternary

Are vacancies counted as a component?

No, vacancies do not count as a component (the fourth element).

Are there case studies available for systems with four or more components?

Yes, please check "MTCSP Quaternary System Exploration Case Study: F-Li-O-V System".

For approaches to multi-element system exploration, please refer to the following documentation:

About MTCSP / Parameter Guide / Multi-Element Systems
About MTCSP / Parameter Guide / Analyzing Multiple Experiments

Which PFP calculation mode is used, and can it be specified?

Generally, specifying the calculation mode is not required. By default, pfp2023compatibility is specified, which automatically selects PBE or PBE_U corresponding to the Materials Project's GGA/GGA+U mixing scheme and anion corrections.

If you are comparing with structures registered in the Materials Project, such as in the following cases, please use pfp2023compatibility as it is:

Discovering new, more stable structures by comparing them with structures registered in the Materials Project.
Finding more stable structures by comparing the results of a derivative structure search with the "Energy above hull" registered in the Materials Project.

If you absolutely need to compare with experimental values or account for dispersion corrections, you can specify the calculation mode. You can also specify the PFP version using the pfp_version argument.

Example: Code for using r2SCAN

search_config = DerivativeStructureSearchConfig.from_feasible_number_mapping(
    feasible_number_mapping=feasible_number_mapping,
    experiment_name=experiment_name,
    pfp_version="v8.0.0",
    pfp_compatibility="R2SCAN", # "PBE", "PBE_PLUS_D3", "R2SCAN_PLUS_D3"
)

For PFP calculation modes, please also refer to the following documentation:
About MTCSP > Formation Energy Calculation with PFP > Formation Energy Corrections and Selection of Calculation Modes

How is the formation energy calculated?

Structures generated by the GA (Genetic Algorithm) undergo structural relaxation of both the cell and atomic positions using PFP, and are then evaluated by calculating their formation energy. The reference structures for pure elements are pre-stored within MTCSP as the most stable structures obtained by re-relaxing candidates retrieved from the Materials Project using PFP. Since this re-relaxation is performed using the same pfp_compatibility and pfp_version as the exploration itself, the energy subtraction for calculating the formation energy remains consistent.

Formula for Calculating Formation Energy:

\[ E_{\mathrm{form}} = E_{\mathrm{compound}} - \sum_i n_i E_i \]

\(E_{\mathrm{form}}\): Formation energy
\(E_{\mathrm{compound}}\): Total energy of the compound
\(E_i\) : Energy per atom of element \(i\) in its pure element reference structure [eV/atom]
\(n_i\) : Number of atoms of element \(i\) in the compound

Note: Relaxation and energy calculations by PFP are static (0 K) calculations, meaning finite-temperature effects such as vibrational entropy and thermal expansion are not included. Because phases stabilized at high temperatures may not appear on the convex hull, we recommend performing separate phonon analysis or similar evaluations for promising candidates.

For detailed information on this topic, please also refer to the following documentation:

Matlantis Example > Formation Energy
About MTCSP > Formation Energy Calculation with PFP
About MTCSP > Formation Energy Calculation with PFP > Elemental Reference Structures
About MTCSP > Limitation > Static (0 K) Energy Calculations

Can the convergence criteria for relaxation calculations be changed?

Unfortunately, the convergence criteria (fmax) for the optimization calculation cannot be changed at this time. To reduce exploration time, please consider other strategies.

Can I obtain the total energy from a single-point calculation instead of the formation energy?

Yes, you can obtain it by extracting CrystalStructure from FrozenExperiment.

frozen = FrozenExperiment(
    experiment_name=experiment_name,
    storage=str(system_config.db_file),
)

for cs in frozen.completed_crystal_structures:
    print(cs.potential_energy)              # Absolute value (eV)
    print(cs.formation_energy)              # Formation energy (eV)
    print(cs.formation_energy_per_atom)     # Formation energy (eV/atom)

Can I obtain the energy distance from the convex hull?

Yes. e_above_hull, which indicates how high each structure sits above the convex hull, serves as an indicator of the thermodynamic stability of the structure (in units of eV/atom).

e_above_hull = 0: On the convex hull, most stable
e_above_hull > 0: Above the convex hull, metastable to unstable (larger values indicate greater instability)

In MTCSP, you can obtain this value during analysis by constructing an MTCSPPhaseDiagram and passing it to FrozenExperiment.get_crystal_structure_info_by_id_list.

While this value can be obtained in both Convex Hull Search and Derivative Structure Search, the method for building the phase_diagram differs between the two.

For Convex Hull Search:
Refer to: Example launcher > Matlantis Example > MTCSP > Convex Hull Analysis (2_2_convex_hull_analysis.ipynb)
For Derivative Structure Search:
Refer to: Example launcher / Matlantis Example / MTCSP / Derivative Structure Analysis (3_2_derivative_structure_analysis.ipynb)

Examples for Convex Hull Search:

from mtcsp.analysis import MTCSPEntry, MTCSPPhaseDiagram

entries = [
    MTCSPEntry.from_crystal_structure(cs)
    for cs in frozen.completed_crystal_structures
]
phase_diagram = MTCSPPhaseDiagram(
    entries,
    elements=frozen.elements,
    reference_entries=frozen.reference_entries,
)

cs_id_list = [cs.id for cs in frozen.completed_crystal_structures]
data = frozen.get_crystal_structure_info_by_id_list(
    cs_id_list,
    phase_diagram=phase_diagram,
)
# Each entry in "data" will contain "energy_above_hull_eV_per_atom"

Can molecular crystals also be handled?

Unfortunately, molecular crystals are not supported. The primary targets of MTCSP are inorganic systems, such as those included in the Materials Project.

For molecular crystals, it is necessary to make assumptions such as treating and maintaining a molecule as a single unit in consideration of covalent bonds. However, MTCSP's GA (Genetic Algorithm) operations function at the atomic level and do not have a mechanism to preserve molecules as distinct units. Consequently, the covalent bonds that must be maintained within a molecular crystal would be broken.

For detailed information on this topic, please also refer to the following documentation (Note that amorphous materials and two-dimensional layered materials are also outside the scope of target crystal types):

About MTCSP > Limitations > Target Crystal Types

Can structures be found where an arbitrary physical property achieves a desired value?

Currently, the optimization target of MTCSP is convex hull search based on formation energy, and optimization calculations targeting arbitrary physical properties cannot be performed. However, it is possible to use Convex Hull Search to find stable structures first, and then individually calculate physical properties to screen them.

For detailed information on this topic, please also refer to the following documentation:

About MTCSP > Limitaitions > No Property-Target Search

Reference: https://tech.preferred.jp/ja/blog/pfp-xrd-csp/ (Japanese only)

How can an exploration be resumed?

By recreating SystemConfig and SearchConfig (or DerivativeStructureSearchConfig) with the same experiment_name and calling perform_hull_search (or perform_derivative_structure_search) again, the exploration results saved in the journal file and AtomsStore will be automatically restored, allowing the exploration to resume from where it left off.

Refer to: Example launcher > Matlantis Example > MTCSP > How to restart/resume experiments (5_1_restart_experiment.ipynb) Note: This is an example for Convex Hull Search.

[For Convex Hull Search]
If you specify a value for n_crystal_structures that is larger than the number of currently completed trials, the exploration will run additionally for the difference between the two values.

For example:

1st run: n_crystal_structures=8 (explores up to 8 structures)
2nd run: n_crystal_structures=20 (specifying the same experiment_name)
In this scenario, the system will additionally explore 12 structures.

Note: Both the journal file and the AtomsStore (atoms_store_dir) are required to resume an exploration.
Note: Using SystemConfig.from_experiment_name (experiment_name) will automatically align the required paths.

How can exploration time be reduced? (Both Modes)

The following methods are available, and multiple methods can be used together.

[For Both Modes]

Adjust `parallelism` according to the notebook specifications

You can specify parallelism as an argument in perform_hull_search for Convex Hull Search, or in perform_derivative_structure_search for Derivative Structure Search.
The recommended values are typically around 6 for a standard notebook, 12 for a 2x notebook, and 24 for a 4x notebook. Please monitor the CPU and memory load while making adjustments.

For Convex Hull Search: Refer to Example launcher > Matlantis Example > MTCSP > Convex Hull Search (2_1_convex_hull_search.ipynb)
For Derivative Structure Search: Refer to Example launcher > Matlantis Example > MTCSP > Derivative Structure Search (3_1_derivative_structure_search.ipynb)

Incorporate past exploration results into the initial population

You can add results from another exploration (FrozenExperiment) or a list of ase.Atoms to the initial GA population for a new exploration. This is effective when you want to utilize high-quality structures previously obtained from a related elemental system, or when you want to use the results of a preliminary search with coarse settings as a starting point for the production search.

Please refer to: Example launcher > Matlantis Example > MTCSP > How to append experiments (5_2_append_experiment.ipynb)

from mtcsp.atoms import FileSystemAtomsStore
from mtcsp.experiment import FrozenExperiment

# Load the source experiment to incorporate
presearch_experiment = FrozenExperiment(
    experiment_name="presearch-experiment-name",
    storage=str(presearch_system_config.db_file),
    atoms_store=FileSystemAtomsStore(presearch_system_config.atoms_store_dir),
)

# Initialize the new experiment
experiment = initialize_hull_search(
    search_config=search_config,
    system_config=system_config,
)

# Incorporate past exploration results (specify the range using e_above_hull)
experiment.add_crystal_structures_from_experiment(
    other_experiment=presearch_experiment,
    e_above_hull=0.1,   # Incorporates structures within 0.1 eV/atom of the convex hull
)

# Continue the exploration as usual
perform_hull_search(
    search_config=search_config,
    system_config=system_config,
    n_crystal_structures=20000,
)

[For Convex Hull Search]
[For Derivative Structure Search]

Convex Hull Search

What is the typical calculation flow for Convex Hull Search?

We provide a tutorial that guides you through the typical workflow of Convex Hull Search (Configuration → Initialization → Execution → Analysis) using minimal code. You can experience the entire process from configuration to phase diagram visualization in a single notebook using a Cu-Au system as an example. Please refer to: Example launcher > Matlantis Example > MTCSP > Quickstart (1_quickstart.ipynb).

For more detailed calculation procedures, please check the subsequent examples: Convex Hull Search (2_1_convex_hull_search.ipynb) and Convex Hull Analysis (2_2_convex_hull_analysis.ipynb).

Calculation Flow of Convex Hull Search:

step	Item	Description	Corresponding Example
1	Configure an exploration	Determine the elemental system and `experiment` name, and create `SystemConfig` and `SearchConfig`.	`2_1_convex_hull_search.ipynb`
2	Initialize an `experiment`	Prepare the `journal` file, `AtomsStore` and initial population (size specified by `population_size`) using `initialize_hull_search`
3	Execute the exploration (Note: This step takes the longest time)	Execute the main process using `perform_hull_search`. Specify the `parallelism` (number of parallel tasks).
4	Analyze the results	Open `FrozenExperiment` to analyze the convex hull and hull energy.	`2_2_convex_hull_analysis.ipynb`

Class, Function, and Term Desctiptions

Item	Descriptions
`SystemConfig`	A configuration class to specify storage locations (`journal` file, `AtomsStore` directory, and log files).
`SearchConfig`	A configuration class to specify exploration conditions (elemental system, `max_atoms`, `population_size` [default: 128], PFP version, etc.)
`max_atoms`	The maximum number of atoms in the generated crystal structures. The default is 32. It is standard to set this to around 32 to 64. Larger values increase the computational load per trial.
`initialize_hull_search`	A function to create the journal file, AtomsStore, and the initial population.
`perform_hull_search`	A function to execute the main exploration process. It specifies `n_crystal_structures` (target number of trials) and `parallelism` (number of parallel tasks).
`FrozenExperiment`	A class used to read exploration results. It is utilized to retrieve completed trials, analyze the convex hull, etc.
`AtomsStore`	A class that saves crystal structure data.
experiment	A single unit of exploration in MTCSP. It is identified by an `experiment_name` and consists of a journal file (metadata) and an AtomsStore (structure data). In Python, it is handled as an Experiment class during execution and as a FrozenExperiment class during analysis.
journal file	A database file that stores information for each trial (equivalent to the storage of an Optuna study for an experiment).
initial population	The initial set of structures for the first generation in the Genetic Algorithm (GA).

What is the recommended value for `n_crystal_structures`?

Please refer to the official Parameter Guide for the recommended values based on the number of elemental species included in your system.

For detailed information on this topic, please also refer to the following documentation:

About MTCSP > Parameter Guide > Convex Hull Search: n_crystal_structures and population_size

How can explorations with constraints be executed? (For Convex Hull Search)

Please refer to Example launcher > Matlantis Example > MTCSP > Convex hull search with Constraints (2_3_convex_hull_search_with_constraints.ipynb). Constraints can be configured using composition_range, composition_endpoints, and oxidation_state_ranges.

Note: Significantly restricting the composition range can make GA (Genetic Algorithm) operations that change the composition less effective, which tends to reduce structural diversity.

Available Constraint Conditions:

`composition_range`

Specifies the lower and upper bounds for the composition ratio of each element.

Example: To restrict Ti\(_x\)O\(_y\) to the range of \(\frac{1}{3} \leq \frac{1}{2}\)

from fractions import Fraction

search_config = SearchConfig(
    elements=("Ti", "O"),
    experiment_name=experiment_name,
    composition_range={
        "Ti": (Fraction(1, 3), Fraction(1, 2)),
        "O":  (Fraction(0), Fraction(1)),
    },
)

Note: All elements constituting the system must be explicitly listed, including those for which the search range is not restricted.

`composition_endpoints`

Specifies the endpoints of the composition space to be explored (the exploration will be conducted within the convex hull formed by these endpoints).

Example: To restrict the search to the triangular composition space formed by SrO-SrO\(_2\)-TiO\(_2\)

search_config = SearchConfig(
    elements=("Sr", "Ti", "O"),
    experiment_name=experiment_name,
    composition_endpoints=["SrO", "SrO2", "TiO2"],
)

Note: Specifying a single composition (e.g., ["SrTiO3"]) enables a search with a fixed composition. However, under a fixed composition, many structures generated by the GA may be rejected for failing to meet the constraints, potentially reducing exploration efficiency.

For detailed information on troubleshooting the "Failed to sample a feasible composition" error, please refer to the following documentation:

About MTCSP > Parameter Guide > Troubleshooting > Initial random structure generation cannot sample a feasible composition

`oxidation_state_ranges`

Specifies the lower and upper bounds for the oxidation state of each element (constrains the allowed compositions based on estimated oxidation states).

Example: To allow only compositions where Sr is \(+2\), Ti is from \(+3\) to \(+4\), and O is \(-2\)

search_config = SearchConfig(
    elements=("Sr", "Ti", "O"),
    experiment_name=experiment_name,
    oxidation_state_ranges={
        "Sr": (2, 2),
        "Ti": (3, 4),
        "O":  (-2, -2),
    },
)

Note: This configuration is ignored in compositional systems where constraints cannot be applied via oxidation states, such as elemental systems (single-element systems) or alloys.

For detailed information on this topic, please also refer to the following documentation:
About MTCSP > Parameter Guide > Troubleshooting > Restricting the Search by Oxidation-State Range

How can exploration time be shortened? (For Convex Hull Search)

[Common to Both Modes]

[For Convex Hull Search]

Reduce `max_atoms`

Reduce max_atoms to make each trial lighter. The default value is 32. It is standard to set this around 32 to 64, and at most around 128.

Narrow Down the Composition Space

Narrow down the composition space using composition_range, composition_endpoints, or oxidation_state_ranges (2_3_convex_hull_search_with_constraints.ipynb). The specific methods are described in the section above.

Add Known Structures from Materials Project to the Initial Population

Set add_mp_crystals_to_initial_population=True to add structures from the Materials Project to the initial population. Known structures available in the Materials Project can be re-relaxed using PFP and then added to the initial population.

For detailed information on this topic, please refer to the following documentation:
About MTCSP > Parameter Guide > Convex Hull Search: n_crystal_structures and population_size

API Key Setup Example:

import os
os.environ["MP_API_KEY"] = "<Your API Key>"

Code Settings Example:

search_config = SearchConfig(
    elements=("Sr", "Ti", "O"),
    experiment_name=experiment_name,
    add_mp_crystals_to_initial_population=True,   # Set this to True
    pfp_version="v9.0.0",
)

[For Derivative Structure Search]

How can the omission of stable phases be reduced? (For Convex Hull Search)

While MTCSP enables exploration across a broad space, it remains theoretically impossible to completely cover every potential material space. Threfore, several approaches can be considered to reduce the omission of stable phases.

For detailed information on this topic, please also refer to the following documentation:
About MTCSP > Limitations > Search Is Not Exhaustive

Recommended Actions:

Run Multiple Independent Explorations

Run multiple independent explorations to broaden and improve overall coverage. Sample code for this approach in multi-element systems is available in the documentation.

For detailed information, please refer to the following documentation:
About MTCSP > Paramter Guide > Analyzing Multiple Experiments

Code Example:

from mtcsp.analysis import get_structures_and_e_above_hull_from_experiments
from mtcsp.atoms import FileSystemAtomsStore
from mtcsp.experiment import FrozenExperiment

exp_sr_ti_o = FrozenExperiment(
    experiment_name="search-Sr-Ti-O",
    storage="search-Sr-Ti-O.journal",          # Added storage
    atoms_store=FileSystemAtomsStore("atoms_store"),
)
exp_sr_mn_o = FrozenExperiment(
    experiment_name="search-Sr-Mn-O",
    storage="search-Sr-Mn-O.journal",
    atoms_store=FileSystemAtomsStore("atoms_store"),
)
exp_ti_mn_o = FrozenExperiment(
    experiment_name="search-Ti-Mn-O",
    storage="search-Ti-Mn-O.journal",
    atoms_store=FileSystemAtomsStore("atoms_store"),
)

results = get_structures_and_e_above_hull_from_experiments(
    [exp_sr_ti_o, exp_sr_mn_o, exp_ti_mn_o],
    max_e_above_hull=0.1,
)

Add Known Structures from Materials Project to the Initial Population

Use add_mp_crystals_to_initial_population to add known structures from the Materials Project to the initial population, utilizing them as a starting point for the exploration. The code sample is described in the section above.

Monitor the Convex Hull Volume

Monitor the convergence of the convex hull volume, and once the discovery of new stable phases is no longer expected, start a new exploration with different settings (such as different constraints).

This approach is utilized within the following Example:
Example launcher > Matlantis Example > MTCSP > Convex Hull Analysis (2_2_convex_hull_analysis.ipynb)

Derivative Structure Search

What is the typical calculation flow for Derivative Structure Search?

Please refer to Example launcher > Matlantis Example > MTCSP > Derivative Structure Search (3_1_derivative_structure_search.ipynb) and Derivative Structure Analysis (3_2_derivative_structure_analysis.ipynb).

step	Item	Description	Corresponding Example
1	Exploration Settings	Determine the base structure, the name of the `experiment`, substitution rules (`feasible_number_mapping`), and create `SystemConfig` and `DerivativeStructureSearchConfig`.	`3_1_derivative_structure_search.ipynb`
2	Initialize `experiment` and Add Derivative Structures	Prepare the jounal file and `AtomsStore` using `initialize_derivative_structure_search`. Then, exhaustively enumerate derivative structures from the base structure using `append_derivative_structures` (specifying the exploration range with `max_index`) and add them to the queue.
3	Execute the exploration (Note: This step takes the most time)	Execute the exploration using `perform_derivative_structure_search`.
4	Result Analysis	Use `FrozenExperiment` to analyze the results.	`3_2_derivative_structure_analysis.ipynb`

Class, Function and Term Descriptions

`Item`	Description
`SystemConfig` (Common to Hull)	A configuration class to specify storage locations (the journal file, AtomsStore directory, and log files).
`DerivativeStructureSearchConfig`	A configuration class to specify the experiment_name, PFP version, and calculation mode. Unlike the `SearchConfig` for Convex Hull Search, the exploration range (base structure, substitution rules, composition, supercell, etc.) is specified separately using functions like `prepare_base_structure_from_atoms` or `append_derivative_structures` rather than within this class. It is typically generated using `from_feasible_number_mapping`.
`prepare_base_structure_from_atoms`	A function to create the base structure data for enumerating derivative structures from an ASE Atoms object and substitution rules (feasible_number_mapping). The composition or composition_range can also be specified here.
`initialize_derivative_structure_search`	A function to create an empty experiment (including the journal file, AtomsStore, etc.).
`append_derivative_structures`	A function to exhaustively enumerate derivative structures from the base structure and add them to the experiment. The range is specified using `max_index`.
`perform_derivative_structure_search`	A function to execute the main exploration process. It specifies `parallelism` (number of parallel tasks).
`FrozenExperiment` (Common to Hull)	A class used to read exploration results. It is utilized to retrieve completed trials, analyze the convex hull, etc.
`AtomsStore` (Common to Hull)	A class that saves crystal structure data.
experiment (Convex to Hull)	A single unit of exploration in MTCSP. Based on the settings in `DerivativeStructureSearchConfig`, it consists of a journal file (metadata), an `AtomsStore` (structure data), and other components. During analysis, results are read using the `FrozenExperiment` class.
journal file (Common to Hull)	A database file that stores information for each trial (equivalent to the storage of an Optuna study for an experiment).
base structure	The prototype structure that serves as the origin for derivative structures. It is specified using a small unit cell, such as a primitive cell.
feasible_number_mapping	A dictionary that specifies the substitutable elements and vacancies for each element included in the base structure.
max_index	Specifies the maximum size of the supercell to be exhaustively enumerated.

Code Example (Conceptual snippet: This code will not run standalone)

# Substitution rules
feasible_number_mapping = {
    atomic_numbers["Cu"]: [atomic_numbers["Cu"], atomic_numbers["Au"]],
}

# Create a base structure (pass feasible_number_mapping)
base_structure = prepare_base_structure_from_atoms(
    atoms=primitive_atoms,
    feasible_number_mapping=feasible_number_mapping,
)

# Create exploration configuration (pass the same feasible_number_mapping)
search_config = DerivativeStructureSearchConfig.from_feasible_number_mapping(
    feasible_number_mapping=feasible_number_mapping,
    experiment_name=experiment_name,
)

# Execute exploration
experiment = initialize_derivative_structure_search(search_config, system_config)
append_derivative_structures(experiment, base_structure, max_index=6)
perform_derivative_structure_search(search_config, system_config, parallelism=6)

How can constraints be applied to the generation of derivative structures?

The generation range of derivative structures can be narrowed down using two criteria: composition, and size/shape.

For detailed usage, please refer to the following Example:
Example launcher > Matlantis Example > MTCSP > Derivative Structure Search with Composition and Supercell(3_3_derivative_structure_search_with_composition_and_supercell.ipynb)

[Composition Constraints]
Specified via the arguments of prepare_base_structure_from_atoms:

arguments	Descriptions
feasible_number_mapping	(Required) Specifies the substitutable elements and vacancies for each element included in the base structure. This must be provided in a dictionary format.
composition	Fixes the composition of the derivative structures using an integer ratio. Example: {Li: 2, Co: 1, Ni: 1, O: 4} fixes the composition to LiCo₀.₅Ni₀.₅O₂.
composition_range	Specifies the composition range for the derivative structures.

[Size and Shape Constraints]

In addition to the standard function append_derivative_structures, two alternative functions are available depending on your objectives:

Function	Description
`append_derivative_structures`	Exhaustively enumerates derivative structures from the base structure and adds them to the experiment. The range is specified using `max_index`.
`append_derivative_structures_with_supercell`	Exhaustively enumerates and adds derivative structures using a specific supercell matrix.
`append_derivative_structures_with_random_sampling`	Randomly samples and adds derivative structures within a range specified by a supercell matrix. This is used when exhaustive enumeration is computationally impractical.

How can exploration time be shortened? (For Derivative Structure Search)

The following methods are available (multiple methods can be used in combination).

[Common to Both Modes]

[For Convex Hull Search]

[For Derivative Structure Search]

Reduce max_index or the Supercell Size

Reduce max_index or the supercell size (the determinant of the matrix) to decrease the size of each derivative structure.

Keep the Number of Generated Structures Within a Realistic Range
Use approx_cumulative_count_derivative_structures to check the estimated number of generated structures, and keep it within a range that can be completed within a realistic calculation time. As a general guideline, the total number of structures should be kept at 100,000 or fewer.

For details, please refer to the following documentation:
About MTCSP > Parametr Guide > Derivative Structure Search: max_index and Structure Count

Narrow Down the Generation Range of Derivative Structures

Please refer to the section above for details.

External References

MTCSP Paper: Phys. Rev. Materials., 10, 063401 (2026)

Related to

Table of Contents

General

What are the key features of Matlantis CSP?

What are the main features?

What is MTCSP Pro?

Are vacancies counted as a component?

Are there case studies available for systems with four or more components?

Which PFP calculation mode is used, and can it be specified?

How is the formation energy calculated?

Can the convergence criteria for relaxation calculations be changed?

Can I obtain the total energy from a single-point calculation instead of the formation energy?

Can I obtain the energy distance from the convex hull?

Can molecular crystals also be handled?

Can structures be found where an arbitrary physical property achieves a desired value?

How can an exploration be resumed?

How can exploration time be reduced? (Both Modes)

Adjust parallelism according to the notebook specifications

Incorporate past exploration results into the initial population

Convex Hull Search

What is the typical calculation flow for Convex Hull Search?

What is the recommended value for n_crystal_structures?

How can explorations with constraints be executed? (For Convex Hull Search)

composition_range

composition_endpoints

oxidation_state_ranges

How can exploration time be shortened? (For Convex Hull Search)

Reduce max_atoms

Narrow Down the Composition Space

Add Known Structures from Materials Project to the Initial Population

How can the omission of stable phases be reduced? (For Convex Hull Search)

Run Multiple Independent Explorations

Add Known Structures from Materials Project to the Initial Population

Monitor the Convex Hull Volume

Derivative Structure Search

What is the typical calculation flow for Derivative Structure Search?

How can constraints be applied to the generation of derivative structures?

How can exploration time be shortened? (For Derivative Structure Search)

Reduce max_index or the Supercell Size

Narrow Down the Generation Range of Derivative Structures

External References

Related articles

Adjust `parallelism` according to the notebook specifications

What is the recommended value for `n_crystal_structures`?

`composition_range`

`composition_endpoints`

`oxidation_state_ranges`

Reduce `max_atoms`