schrodinger.application.matsci.msml.device.formulations module¶

Utilities for device design and device machine learning

class schrodinger.application.matsci.msml.device.formulations.LayerSpec(key: str, display_name: str = '', colors: tuple = (), component_input_modes: tuple = ('smiles',), descriptor_column_patterns: tuple = ())¶

Bases: object

Configuration for one logical layer type in a layered device.

component_input_modes describes how the layer’s component identities are represented in formulation input data. Most molecular layers use COMPONENT_INPUT_SMILES; layers for inorganic or otherwise non-SMILES materials may instead use named missing-SMILES labels, descriptor-only inputs, or descriptor-backed labels.

descriptor_column_patterns identifies layer-associated additional feature columns in the input CSV. These columns describe the layer or its material, but are not component identity columns. Patterns use shell-style wildcards, such as Absorber_*_band_gap or ETL_*_mobility.

key: str¶

display_name: str = ''¶

colors: tuple = ()¶

component_input_modes: tuple = ('smiles',)¶

descriptor_column_patterns: tuple = ()¶

getDisplayName()¶

Return the user-facing layer name.

Returns:: User-facing layer name
Return type:: str

allowsComponentInputMode(component_input_mode)¶

Return whether this layer accepts a component input mode.

Parameters:: component_input_mode (str) – Component input mode identifier
Returns:: True if this mode is accepted, False otherwise
Return type:: bool

allowsMissingSmilesLabels()¶

Return whether non-SMILES components can be encoded as named missing SMILES ingredients for this layer.

Returns:: True if named missing-SMILES labels are allowed
Return type:: bool

matchesDescriptorColumn(column)¶

Return whether a CSV column is a descriptor declared by this layer.

Parameters:: column (str) – CSV column name
Returns:: True if the column matches a layer descriptor, False otherwise
Return type:: bool

toDict()¶

Return a JSON-serializable representation of the layer spec.

Returns:: Serialized layer spec
Return type:: dict

classmethod fromDict(data)¶

Create a layer spec from serialized data.

Parameters:: data (dict) – Serialized layer spec
Returns:: Layer spec created from serialized data
Return type:: LayerSpec

__init__(key: str, display_name: str = '', colors: tuple = (), component_input_modes: tuple = ('smiles',), descriptor_column_patterns: tuple = ()) → None¶

class schrodinger.application.matsci.msml.device.formulations.LayerMergeRule(layer_keys: tuple, display_name: str = '', same_index: bool = True, include_sublayer_thickness: bool = False, include_sublayer_weight_percent: bool = True)¶

Bases: object

Configuration for displaying/exporting multiple logical layers as one merged device layer.

layer_keys: tuple¶

display_name: str = ''¶

same_index: bool = True¶

include_sublayer_thickness: bool = False¶

include_sublayer_weight_percent: bool = True¶

matches(layer_keys)¶

Return whether this rule matches the ordered layer keys.

Parameters:: layer_keys (tuple(str)) – Ordered layer type keys
Returns:: True if this rule matches the layer keys, False otherwise
Return type:: bool

toDict()¶

Return a JSON-serializable representation of the merge rule.

Returns:: Serialized merge rule
Return type:: dict

classmethod fromDict(data)¶

Create a merge rule from serialized data.

Parameters:: data (dict) – Serialized merge rule
Returns:: Merge rule created from serialized data
Return type:: LayerMergeRule

__init__(layer_keys: tuple, display_name: str = '', same_index: bool = True, include_sublayer_thickness: bool = False, include_sublayer_weight_percent: bool = True) → None¶

class schrodinger.application.matsci.msml.device.formulations.LayeredDeviceTargetSpec(key: str, display_name: str = '', short_label: str = '', unit: str = '', optimization: str = '', display_range: tuple = ())¶

Bases: object

Metadata for a target property commonly used by a layered-device workflow.

Target specs are UI and workflow hints for Studio-style panels, such as labels, units, optimization goals, and plotting ranges. They do not restrict which CSV columns can be used as model training targets.

optimization describes how workflow templates should rank or screen a target, such as maximize for efficiency or minimize for voltage. It is advisory metadata rather than backend validation.

display_range stores preferred visualization bounds for controls, plots, and color scales. It should not be treated as the allowed numerical range for training data.

key: str¶

display_name: str = ''¶

short_label: str = ''¶

unit: str = ''¶

optimization: str = ''¶

display_range: tuple = ()¶

toDict()¶

Return a JSON-serializable representation of the target spec.

Returns:: Serialized target spec
Return type:: dict

classmethod fromDict(data)¶

Create a target spec from serialized data.

Parameters:: data (dict) – Serialized target spec
Returns:: Target spec created from serialized data
Return type:: LayeredDeviceTargetSpec

__init__(key: str, display_name: str = '', short_label: str = '', unit: str = '', optimization: str = '', display_range: tuple = ()) → None¶

class schrodinger.application.matsci.msml.device.formulations.LayeredDeviceDescriptorSpec(key: str, display_name: str = '', unit: str = '', source: str = '', required: bool = False, column_patterns: tuple = ())¶

Bases: object

Metadata for an additional device or material descriptor.

source identifies where the descriptor family comes from, such as a built-in descriptor engine or a user-provided descriptor table. It is workflow metadata only, not a file path.

column_patterns identifies generated or supplied CSV columns belonging to this descriptor family. Patterns use shell-style wildcards; if omitted, the descriptor key is treated as an exact column name.

required marks descriptor families that a Studio workflow should create or validate before training or screening. Matching columns are still handled by the backend as ordinary additional feature columns.

key: str¶

display_name: str = ''¶

unit: str = ''¶

source: str = ''¶

required: bool = False¶

column_patterns: tuple = ()¶

getColumnPatterns()¶

Return CSV column patterns for this descriptor. If no explicit pattern is configured, the descriptor key itself is treated as an exact column.

Returns:: CSV column patterns for this descriptor
Return type:: tuple(str)

matchesColumn(column)¶

Return whether a CSV column matches this descriptor declaration.

Parameters:: column (str) – CSV column name
Returns:: True if the column matches this descriptor, False otherwise
Return type:: bool

toDict()¶

Return a JSON-serializable representation of the descriptor spec.

Returns:: Serialized descriptor spec
Return type:: dict

classmethod fromDict(data)¶

Create a descriptor spec from serialized data.

Parameters:: data (dict) – Serialized descriptor spec
Returns:: Descriptor spec created from serialized data
Return type:: LayeredDeviceDescriptorSpec

__init__(key: str, display_name: str = '', unit: str = '', source: str = '', required: bool = False, column_patterns: tuple = ()) → None¶

class schrodinger.application.matsci.msml.device.formulations.LayeredDeviceSpec(spec_id: str, display_name: str, layers: tuple, default_layers: tuple = (), merge_rules: tuple = (), allow_unknown_layers: bool = False, targets: tuple = (), descriptors: tuple = (), device_descriptor_column_patterns: tuple = (), material_library_refs: tuple = ())¶

Bases: object

Configuration for a layered-device formulation model.

targets and descriptors are optional Studio workflow metadata. They describe common target properties and descriptor families without limiting the backend to those targets or features.

device_descriptor_column_patterns identifies device-level additional feature columns that are not associated with a particular layer.

material_library_refs stores references to material libraries or descriptor tables a Studio-style workflow can offer alongside the spec.

spec_id: str¶

display_name: str¶

layers: tuple¶

default_layers: tuple = ()¶

merge_rules: tuple = ()¶

allow_unknown_layers: bool = False¶

targets: tuple = ()¶

descriptors: tuple = ()¶

device_descriptor_column_patterns: tuple = ()¶

material_library_refs: tuple = ()¶

property layer_keys¶

Ordered layer type keys supported by this spec.

Returns:: Ordered layer type keys
Return type:: tuple(str)

property layer_map¶

Mapping of layer type key to LayerSpec.

Returns:: Mapping of layer type key to layer spec
Return type:: dict(str, LayerSpec)

property descriptor_keys¶

Ordered descriptor keys declared by this spec.

Returns:: Ordered descriptor keys
Return type:: tuple(str)

property target_keys¶

Ordered target keys declared by this spec.

Returns:: Ordered target keys
Return type:: tuple(str)

getLayerSpec(layer_key)¶

Return the LayerSpec for the given layer type.

Parameters:: layer_key (str) – Layer type key
Returns:: Layer spec for the layer type, or None if unavailable
Return type:: LayerSpec or None

getLayerOrderIndex(layer_key)¶

Return the sort index for the given layer type. Unknown layers sort after configured layers.

Parameters:: layer_key (str) – Layer type key
Returns:: Sort index for the layer type
Return type:: int

isLayerAllowed(layer_key)¶

Return whether the layer type is allowed by this spec.

Parameters:: layer_key (str) – Layer type key
Returns:: True if the layer type is allowed, False otherwise
Return type:: bool

getLayerColor(layer_key, index)¶

Return the configured layer color in RGB 0-255 format.

Parameters:

layer_key (str) – Layer type key
index (int) – Layer index

Returns:

Configured layer color in RGB 0-255 format

Return type:

tuple(int, int, int)

getMergeRule(layer_keys)¶

Return the merge rule matching the ordered layer type keys.

Parameters:: layer_keys (tuple(str)) – Ordered layer type keys
Returns:: Matching merge rule, or None if no rule matches
Return type:: LayerMergeRule or None

allowsMissingSmilesLabels()¶

Return whether this spec allows non-SMILES components to be encoded as named missing SMILES ingredients.

Returns:: True if named missing-SMILES labels are allowed
Return type:: bool

getDescriptorColumnPatterns()¶

Return all CSV descriptor column patterns declared by this spec.

Returns:: CSV descriptor column patterns declared by this spec
Return type:: tuple(str)

matchesDescriptorColumn(column)¶

Return whether a CSV column is an additional descriptor for this spec.

Parameters:: column (str) – CSV column name
Returns:: True if the column matches a descriptor, False otherwise
Return type:: bool

getMatchingDescriptorColumns(columns)¶

Return columns from columns declared as descriptors by this spec.

Parameters:: columns (iterable(str)) – CSV column names
Returns:: Columns declared as descriptors by this spec
Return type:: list(str)

toDict()¶

Return a JSON-serializable representation of the device spec.

Returns:: Serialized layered-device spec
Return type:: dict

classmethod fromDict(data)¶

Create a device spec from serialized data.

Parameters:: data (dict) – Serialized layered device spec
Returns:: Layered-device spec created from serialized data
Return type:: LayeredDeviceSpec

__init__(spec_id: str, display_name: str, layers: tuple, default_layers: tuple = (), merge_rules: tuple = (), allow_unknown_layers: bool = False, targets: tuple = (), descriptors: tuple = (), device_descriptor_column_patterns: tuple = (), material_library_refs: tuple = ()) → None¶

schrodinger.application.matsci.msml.device.formulations.get_layered_device_spec(spec_id)¶

Return a registered layered-device spec.

Parameters:: spec_id (str) – Spec ID
Returns:: Registered layered-device spec
Return type:: LayeredDeviceSpec

schrodinger.application.matsci.msml.device.formulations.get_layered_device_spec_display_name(spec_id)¶

Return the display name for a layered-device spec ID.

Parameters:: spec_id (str) – Spec ID
Returns:: Display name for the spec ID
Return type:: str

schrodinger.application.matsci.msml.device.formulations.register_layered_device_spec(device_spec)¶

Register a layered-device spec.

Parameters:: device_spec (LayeredDeviceSpec) – Spec to register

schrodinger.application.matsci.msml.device.formulations.is_builtin_layered_device_spec(spec_id)¶

Return whether the layered-device spec id is provided by mmshare.

Parameters:: spec_id (str) – Spec ID
Returns:: True if the spec is built in, False otherwise
Return type:: bool

schrodinger.application.matsci.msml.device.formulations.get_layered_device_specs_dir()¶

Return the user data directory for serialized layered-device specs.

Returns:: User data directory for serialized layered-device specs
Return type:: str

schrodinger.application.matsci.msml.device.formulations.get_user_layered_device_spec_json_path(spec_id)¶

Return the user JSON path for a layered-device spec id.

Parameters:: spec_id (str) – Spec ID
Returns:: User JSON path for the spec ID
Return type:: str

schrodinger.application.matsci.msml.device.formulations.write_layered_device_spec_json(device_spec, filename)¶

Write a layered-device spec to a JSON file.

Parameters:

device_spec (LayeredDeviceSpec) – Spec to serialize
filename (str) – Output JSON path

schrodinger.application.matsci.msml.device.formulations.write_user_layered_device_spec(device_spec)¶

Write a user layered-device spec to the matsci user data directory.

Parameters:: device_spec (LayeredDeviceSpec) – Spec to serialize
Returns:: The written JSON path
Return type:: str

schrodinger.application.matsci.msml.device.formulations.read_layered_device_spec_json(filename)¶

Read a layered-device spec from a JSON file.

Parameters:: filename (str) – Input JSON path
Returns:: Layered-device spec read from the JSON file
Return type:: LayeredDeviceSpec

schrodinger.application.matsci.msml.device.formulations.load_user_layered_device_specs()¶

Load and register user layered-device specs from the matsci user data directory. Built-in spec ids are ignored so user JSON files cannot override shipped specs.

Returns:: User layered-device specs keyed by spec ID
Return type:: dict(str, LayeredDeviceSpec)

schrodinger.application.matsci.msml.device.formulations.get_oled_layer_color(layer_type, index)¶

Get the color of the OLED layer

Parameters:

layer_type (str) – The type of the layer
index (int) – The index of the layer

Returns:

The color of the layer in RGB 0-255 format

Return type:

tuple

schrodinger.application.matsci.msml.device.formulations.is_layer_allowed(layer_type, layer_index=None, allowed_layers=None)¶

Check if the layer is allowed in the OLED stack

Parameters:

layer_type (str) – The type of the layer
layer_index (int or None) – Deprecated. Index validation removed - parameter ignored and will be removed in future version
allowed_layers (dict or None) – The allowed layers types as a dictionary and the values are lists of layer names, if None, use the default OLED_PREDEFINED_LAYERS

Returns:

True if the layer type is allowed, False otherwise

Return type:

bool

schrodinger.application.matsci.msml.device.formulations.get_max_layer_index(layer_type, all_layers=None)¶

Get the maximum index of the layer

Parameters:

layer_type (str) – The type of the layer
all_layers (dict or None) – The allowed layers types as a dictionary and the values are lists of layer names or None to use the default OLED_PREDEFINED_LAYERS

Returns:

The maximum index of the layer

Return type:

int