generate_derivative_structures

Command-line usage

usage: cell generate_derivative_structures [-h] [-scsi None] [-sno]
                                           [-nsl None] [-ssfp None]
                                           [-ssgfp None] [-mfp None]
                                           [-plfp None] [-dssfp dss.pickle]
                                           [-dssfps None] [-mmns None]
                                           [-mdssfp None] [-plab None]
                                           [-plabs None] [-psol None]
                                           [-scsh None] [-pfu] [-lref None]
                                           [-mn None] [-n-lowest 1]
                                           [-n-random 0] [-random-state None]
                                           [-task do_full_enumeration]
                                           [-y None] [-ymin None] [-ymax None]
                                           [-sp True] [-svp True] [-sep False]
                                           [-pf property_vs_concentration.png]
                                           [-skip] [-rec]
                                           [colors] [markers] [sizes]

positional arguments:
  colors                [None]
  markers               [None]
  sizes                 [None]

options:
  -h, --help            show this help message and exit
  -scsi, --sc-sizes None
                        List of supercell sizes.
  -sno, --shapes-nearest-orthogonal
                        Generate supercell shapes with angles closest to
                        orthogonal
  -nsl, --nsubs-list None
                        List of lists indicating number of substitutions for
                        each supercell.
  -ssfp, --sset-filepath None
                        Path to a serialized StructuresSet object.
  -ssgfp, --sset-gss-filepath None
                        Path to a serialized GSS StructuresSet object.
  -mfp, --model-filepath None
                        Filepath of a serialized CE model object.
  -plfp, --plat-filepath None
                        Filepath of a serialized ParentLattice object.
  -dssfp, --dss-filepath dss.pickle
                        Filepath to serialize or retrieve derivative
                        structures.
  -dssfps, --dss-filepaths None
                        List of filepaths to existing derivative structures
                        for task=merge_dsses.
  -mmns, --merge-mask-names None
                        For task=merge_dsses: list of mask names, one per
                        source in dss_filepaths. Use None for a source to
                        include all its configurations.
  -mdssfp, --merged-dss-filepath None
                        Filepath to serialize or retrieve merged derivative
                        structures.
  -plab, --property-name None
                        Name of the property to request from the structures
                        set.
  -plabs, --property-names None
                        Names of the property to request from the structures
                        set.
  -psol, --property-solver None
                        Dictionary of parameters for the property solver.
  -scsh, --sc-shape None
                        3x3 integer matrix to specify supercell shape.
  -pfu, --per-formula-unit
                        Flag: compute per formula unit.
  -lref, --linear-reference None
                        Linear reference for property correction.
  -mn, --mask-name None
                        Name of the mask for applicable tasks.
  -n-lowest 1           Number of lowest-energy structures to include.
  -n-random 0           Task-dependent number of random structures.
  -random-state None    Seed for random number generators.
  -task, --task do_full_enumeration
                        Task to perform.
  -y, --y-axis-label None
                        Label for the y-axis of the plot.
  -ymin None            Minimum y-value for the plot axis.
  -ymax None            Maximum y-value for the plot axis.
  -sp, --show-plot True
                        If True, show the plot in a new window.
  -svp, --save-plot True
                        If True, save the plot to file.
  -sep, --store-ensemble-predictions False
                        If True, for task compute_property_with_ce_model, and
                        if the model in model_filepath is a bagging regressor.
  -pf, --plot-fname property_vs_concentration.png
                        Filepath to save the plot at.
  -skip, --skip-existing
                        when adding binary complements, skip those that
                        already exist in the DSS instead of raising an error
  -rec, --non-recursive
                        Use slow non-recursive method for finding derivative
                        structures

Arguments and behavior

clusterx.cli.generate_derivative_structures.generate_derivative_structures(sc_sizes=None, shapes_nearest_orthogonal=False, nsubs_list=None, sset_filepath=None, sset_gss_filepath=None, model_filepath=None, plat_filepath=None, dss_filepath='dss.pickle', dss_filepaths=None, merge_mask_names=None, merged_dss_filepath=None, property_name=None, property_names=None, property_solver=None, sc_shape=None, per_formula_unit=False, linear_reference=None, mask_name=None, n_lowest=1, n_random=0, random_state=None, task='do_full_enumeration', y_axis_label=None, ymin=None, ymax=None, show_plot=True, save_plot=True, store_ensemble_predictions=False, plot_fname='property_vs_concentration.png', colors=None, markers=None, sizes=None, skip_existing=False, non_recursive=False)

Generate derivative structures and (optionally) compute/plot properties.

This command wraps several workflows around clusterx.derivative_structures.DerivativeStructures, clusterx.parent_lattice.ParentLattice, and clusterx.model.Model. The behavior is controlled by task (see Tasks below).

By default, results are serialized to dss.pickle (a pickled DerivativeStructures with its generated configurations and masks). Some tasks may also produce plots or update properties inside the serialized object.

Typical flow

  1. Enumerate or randomly sample derivative structures from a parent lattice.

  2. Compute a property for every configuration (via CE model, calculator, or a custom solver).

  3. Post-process (e.g., mark lowest values per concentration) and/or visualize.

Parameters:
sc_sizeslist[int], optional

Supercell sizes to consider during enumeration/random generation.

shapes_nearest_orthogonalbool or list[int], default False

If True (or a list of shape IDs), prefer supercell shapes with angles closest to orthogonal.

nsubs_listint or list[int] or list[list[int]], optional

Number(s) of substitutions per supercell (can be a single int, a list, or a list per shape).

sset_filepathstr, optional

Path to a serialized clusterx.structures_set.StructuresSet (needed by some plotting tasks).

model_filepathstr, optional

Path to a serialized clusterx.model.Model used for CE predictions.

plat_filepathstr, optional

Path to a serialized clusterx.parent_lattice.ParentLattice (required by enumeration/random tasks).

dss_filepathstr, default “dss.pickle”

Output/input pickle filepath for the clusterx.derivative_structures.DerivativeStructures.

dss_filepathslist[str], optional

Input filepaths for task="merge_dsses".

merge_mask_nameslist[str | None], optional

For task="merge_dsses", mask names to apply per input source (same length as dss_filepaths). Use None to include all configurations for that source.

property_namestr, optional

Single property name to compute/plot. Mutually exclusive with property_names.

property_nameslist[str], optional

Multiple property names to compute/plot. Mutually exclusive with property_name.

property_solverdict, optional

Configuration for the custom solver used by task="compute_property_with_custom_solver". Provide filename (path to a Python module) and exactly one of:

  • function: name of a module-level function to call.

  • classname: name of a solver class. Optionally provide method (defaults to "compute_property") to select a method on its instance.

Optionally provide kwargs (a dictionary passed to the selected callable).

sc_shapeint or list[int] or list[list[int]], optional

Supercell shape specification. May be a scalar multiplier or an explicit 3×3 integer matrix.

per_formula_unitbool, default False

If True, compute/scale properties per formula unit.

linear_referencelist[list[float]] or list[dict] or str, optional

Linear-reference definition, active for task="compute_property_with_ce_model" (or "compute_property_ce") and task="compute_property_with_custom_solver". The linear reference is subtracted to the computed property. Pass two concentration/property points as [[x0, p0], [x1, p1]] or [{'x': x0, 'y': p0}, {'x': x1, 'y': p1}], or use "least-squares" / "concentration-endpoints" to define a reference by fitting the computed values. None disables the linear-reference. The behavior and constraints are documented in clusterx.derivative_structures.DerivativeStructures.compute_properties().

mask_namestr or list[str | None], optional

Name of a mask to write/read within the serialized DSS object for downstream filtering. For task=merge_dsses, a single string applies the same mask to all sources; a list is interpreted as per-source masks.

n_lowestint, default 1

Count of lowest-value configurations per concentration to mark (used by "mark_lowest_property_per_concentration" / "mark_lowest_and_random_properties_per_concentration").

n_randomint, default 0

Task-dependent number of random configurations:

  • For task="random", the number to generate for each (supercell shape, substitution count) pair.

  • For task="mark_lowest_and_random_properties_per_concentration", the number to sample per concentration and add to the mask alongside the n_lowest configurations. Duplicates are removed, so fewer than n_random additional configurations may be marked.

random_stateint, optional

Seed for random selection/generation.

taskstr, default “do_full_enumeration”

Selects the workflow to run. See Tasks below.

plotdata_filepathstr, optional

When plotting multiple series, save the plotted .npz data to this path.

colors, markers, sizeslist, optional

Styling for multi-series scatter plots (length should match the number of series).

non_recursivebool, default False

If True, use the slower non-recursive enumeration method.

Returns:
None

Results are persisted to dss_filepath and/or sset_filepath; some tasks display plots.

Notes

  • Exactly one of property_name or property_names should be provided when computing/plotting properties.

  • The serialized DSS object contains: configurations (DataFrame), masks (dict of config_id arrays), and supercell shape metadata used by conversion/plotting tasks.

CLI flags (plac)

Many parameters are exposed via short options when used as a CLI command:

  • --scsi → sc_sizes

  • --sno → shapes_nearest_orthogonal (flag)

  • --nsl → nsubs_list

  • --ssfp → sset_filepath

  • --mfp → model_filepath

  • --plfp → plat_filepath

  • --dssfp → dss_filepath

  • --dssfps → dss_filepaths

  • --mmns → merge_mask_names

  • --plab → property_name

  • --plabs → property_names

  • --psol → property_solver

  • --scsh → sc_shape

  • --pfu → per_formula_unit (flag)

  • --lref → linear_reference

  • --mn → mask_name

  • --task → task

  • --rec → sets non_recursive=True (use non-recursive enumeration)

Tasks

"random"

Randomly generate up to n_random unique configurations per (supercell shape, substitution count) under the given constraints. Writes the resulting DSS to dss_filepath.

"do_full_enumeration" or "find_derivative_structures"

Exhaustively enumerate derivative structures for the given lattice/sizes/shapes. Writes the resulting DSS to dss_filepath. Honor non_recursive.

"compute_property_with_ce_model" or "compute_property_ce"

Compute property_name (or property_names) for all configurations in dss_filepath using the CE model from model_filepath. Supports per_formula_unit and linear_reference.

"compute_property_with_custom_solver"

Load and call the module-level function or class method selected by property_solver for every configuration via clusterx.derivative_structures.DerivativeStructures.compute_properties(). The selected callable receives the generated clusterX structure, its 3×3 supercell shape, the binary fractional concentration, and the configuration’s pandas Series as row; optional property_solver["kwargs"] are forwarded as keyword arguments. Return one scalar when property_name is set, or an ordered sequence with one value per entry in property_names. The CLI passes these arguments through to compute_properties; see its docstring for details on return values, per_formula_unit, and linear_reference.

"plot_property_vs_concentration" / "plot_property"

Scatter plot property vs fractional concentration. If sset_filepath and model_filepath are given, overlays CE predictions.

"plot_predictions_vs_target"

Quick diagnostic scatter: target values vs CE predictions for property_name using sset_filepath and model_filepath.

"plot_property_vs_concentration2" / "plot_property_vs_concentration3"

Alternative interactive visualizations (Bokeh / Plotly).

"mark_lowest_property_per_concentration"

Create a mask with the configuration of minimal property_name for each concentration bin.

"mark_lowest_and_random_properties_per_concentration"

Create a mask with the n_lowest best plus up to n_random randomly sampled configurations per concentration.

"to_sset" / "convert_to_sset"

Convert the stored configurations (optionally filtered by mask_name) into a clusterx.structures_set.StructuresSet written to sset_filepath.

Examples

1) Create a set of random structures and serialize them

[generate_derivative_structures]
task = "random"
plat_filepath = "plat.json"
sc_shape = 2
nsubs_list = [0, 2, 4, 6, 8]
n_random = 5
random_state = 1
dss_filepath = "random_structures.pickle"

2) Define a custom solver function

Save a module-level function in a Python file, for example my_custom_solvers.py. Functions follow the callable interface documented by clusterx.derivative_structures.DerivativeStructures.compute_properties():

def compute_energy(structure, shape, concentration, row, scale=1.0):
    # Replace this example calculation with the desired property.
    return scale * concentration

3) Run a custom solver function

[generate_derivative_structures]
task = "compute_property_with_custom_solver"
property_solver = { filename = "path/to/my_custom_solvers.py",
                    function = "compute_energy",
                    kwargs = { scale = 2.0 } }
dss_filepath = "random_structures.pickle"
property_name = "energy"
  1. Select a method from a solver class

Use a class when you want to group related solvers or share instance state. The class is instantiated without arguments. The method key selects which instance method is called; if omitted, it defaults to "compute_property".

class MySolvers:
    def compute_property_1(
        self, structure, shape, concentration, row, scale=1.0, offset=0.0
    ):
        return scale * concentration + offset

    def compute_property_2(
        self, structure, shape, concentration, row, normal=3.0, parity=2.0
    ):
        return row["property"] * concentration / normal + parity
[generate_derivative_structures]
task = "compute_property_with_custom_solver"
property_solver = { filename = "path/to/my_custom_solvers.py",
                    classname = "MySolvers",
                    method = "compute_property_2",
                    kwargs = { normal = 3.0, parity = 2.0 } }
dss_filepath = "random_structures.pickle"
property_name = "property_2"

5) Merge multiple DSS files with optional per-source masks

[generate_derivative_structures]
task = "merge_dsses"
dss_filepaths = ["a.pickle", "b.pickle", "c.pickle"]
merged_dss_filepath = "merged.pickle"
# One entry per source; None means include all configurations from that source
merge_mask_names = ["lowest", "candidate_pool", "none"]

You can also provide a single mask_name to apply the same mask to all sources during merge.

For the custom solver callable contract, including multi-property return values, see clusterx.derivative_structures.DerivativeStructures.compute_properties().