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, andclusterx.model.Model. The behavior is controlled bytask(see Tasks below).By default, results are serialized to
dss.pickle(a pickledDerivativeStructureswith its generated configurations and masks). Some tasks may also produce plots or update properties inside the serialized object.Typical flow
Enumerate or randomly sample derivative structures from a parent lattice.
Compute a property for every configuration (via CE model, calculator, or a custom solver).
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.Modelused 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 asdss_filepaths). UseNoneto 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". Providefilename(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 providemethod(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") andtask="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.Nonedisables the linear-reference. The behavior and constraints are documented inclusterx.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 then_lowestconfigurations. Duplicates are removed, so fewer thann_randomadditional 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
.npzdata 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_filepathand/orsset_filepath; some tasks display plots.
Notes
Exactly one of
property_nameorproperty_namesshould 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→ setsnon_recursive=True(use non-recursive enumeration)
Tasks
"random"Randomly generate up to
n_randomunique configurations per (supercell shape, substitution count) under the given constraints. Writes the resulting DSS todss_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. Honornon_recursive."compute_property_with_ce_model"or"compute_property_ce"Compute
property_name(orproperty_names) for all configurations indss_filepathusing the CE model frommodel_filepath. Supportsper_formula_unitandlinear_reference."compute_property_with_custom_solver"Load and call the module-level function or class method selected by
property_solverfor every configuration viaclusterx.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 asrow; optionalproperty_solver["kwargs"]are forwarded as keyword arguments. Return one scalar whenproperty_nameis set, or an ordered sequence with one value per entry inproperty_names. The CLI passes these arguments through tocompute_properties; see its docstring for details on return values,per_formula_unit, andlinear_reference."plot_property_vs_concentration"/"plot_property"Scatter plot property vs fractional concentration. If
sset_filepathandmodel_filepathare given, overlays CE predictions."plot_predictions_vs_target"Quick diagnostic scatter: target values vs CE predictions for
property_nameusingsset_filepathandmodel_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_namefor each concentration bin."mark_lowest_and_random_properties_per_concentration"Create a mask with the
n_lowestbest plus up ton_randomrandomly sampled configurations per concentration."to_sset"/"convert_to_sset"Convert the stored configurations (optionally filtered by
mask_name) into aclusterx.structures_set.StructuresSetwritten tosset_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 byclusterx.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"
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
methodkey 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_nameto 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().