sisl.viz.FatbandsPlot

class sisl.viz.FatbandsPlot(bands_data: BandsData, Erange: Tuple[float, float] | None = None, E0: float = 0.0, E_axis: Literal['x', 'y'] = 'y', bands_range: Tuple[int, int] | None = None, spin: Literal[0, 1] | None = None, bands_style: StyleSpec = {'color': 'black', 'opacity': 1, 'width': 1}, spindown_style: StyleSpec = {'color': 'blue', 'width': 1}, gap: bool = False, gap_tol: float = 0.01, gap_color: str = 'red', gap_marker: dict = {'size': 7}, direct_gaps_only: bool = False, custom_gaps: Sequence[Dict] = [], bands_mode: Literal['line', 'scatter', 'area_line'] = 'line', groups: OrbitalQueries = [], fatbands_var: str = 'norm2', fatbands_mode: Literal['line', 'scatter', 'area_line'] = 'area_line', fatbands_scale: float = 1.0, backend: str = 'plotly')[source]

Bases: OrbitalGroupsPlot

Plots band structure energies showing the contribution of orbitals to each state.

Parameters:

bands_data (BandsData) – The object containing the data to plot.
Erange (Optional[Tuple[float, float]]) – The energy range to plot. If None, the range is determined by bands_range.
E0 (float) – The energy reference.
E_axis (Literal['x', 'y']) – Axis to plot the energies.
bands_range (Optional[Tuple[int, int]]) – The bands to plot. Only used if Erange is None. If None, the 15 bands above and below the Fermi level are plotted.
spin (Optional[Literal[0, 1]]) – Which spin channel to display. Only meaningful for spin-polarized calculations. If None and the calculation is spin polarized, both are plotted.
bands_style (StyleSpec) – Styling attributes for bands.
spindown_style (StyleSpec) – Styling attributes for the spin down bands (if present). Any missing attribute will be taken from bands_style.
gap (bool) – Whether to display the gap.
gap_tol (float) – Tolerance in k for determining whether two gaps are the same.
gap_color (str) – Color of the gap.
gap_marker (dict) – Marker styles for the gap (as plotly marker’s styles).
direct_gaps_only (bool) – Whether to only display direct gaps.
custom_gaps (Sequence[Dict]) – List of custom gaps to display. See the showcase notebooks for examples.
bands_mode (Literal['line', 'scatter', 'area_line']) – The method used to draw the band lines.
groups (OrbitalQueries) – Orbital groups to plots. See showcase notebook for examples.
fatbands_var (str) – The variable to use from bands_data to determine the width of the fatbands. This variable must have as coordinates (k, band, orb, [spin]).
fatbands_mode (Literal['line', 'scatter', 'area_line']) – The method used to draw the fatbands.
fatbands_scale (float) – Factor that scales the size of all fatbands.
backend (str) – The backend to use to generate the figure.

Return type:

Figure

Methods

`add_group`([group, clean])	Adds a new orbitals group.
`evaluate_input_node`(node)
`final_node_key`(*args)	Returns the key of the final (output) node of the workflow.
`find_node_key`(node, *args)	Returns the identifier key of a node in this workflow
`from_func`([func, context, module])	Builds a node from a function.
`from_node_tree`(output_node[, workflow_name])	Creates a workflow class from a node.
`function`(bands_data[, Erange, E0, E_axis, ...])	Plots band structure energies showing the contribution of orbitals to each state.
`get`()	Returns the up to date output of the workflow.
`get_diagram_label`()	Returns the label to be used in diagrams when displaying this node.
`get_input`(key)
`get_tree`()
`groups`(*i_or_names)	Gets the groups that match your query
`is_output_outdated`(evaluated_inputs)	Checks if the node needs to be ran
`map_inputs`(inputs, func[, only_nodes, exclude])	Maps all inputs of the node applying a given function.
`merge`(others, *kwargs)
`plot_class_key`()
`recursive_update_inputs`([cls])	Updates the inputs of the node recursively.
`remove_groups`(*i_or_names[, all])	Removes orbital groups.
`setup`(args, *kwargs)	Sets up the node based on its initial inputs.
`split_groups`(*i_or_names[, on, only, ...])	Splits the orbital groups into multiple groups.
`split_orbs`([on, only, exclude, clean])	Splits the orbitals into different groups.
`update_groups`(i_or_names, *kwargs)	Updates existing groups.
`update_inputs`(**inputs)	Updates the inputs of the workflow.
`update_settings`(args, *kwargs)
`DELETE_KWARG`
`context`
`default_inputs`
`dryrun_nodes`
`inputs`
`last_log`	Last time the logs of this node were updated
`network`
`nodes`
`logs`

DELETE_KWARG = <object object>

__call__(*args, **kwargs): Call self as a function.

__init__(*args, **kwargs)

add_group(group={}, clean=False, **kwargs)

Adds a new orbitals group.

The new group can be passed as a dict or as keyword arguments. The keyword arguments will overwrite what has been passed as a dict if there is conflict.

Parameters:

group (dict, optional) – the new group as a dictionary
clean (boolean, optional) – whether the plot should be cleaned before drawing the group. If False, the group will be drawn on top of what is already there.
**kwargs – parameters of the group can be passed as keyword arguments too. They will overwrite the values in req

context: NodeContext = NodeContext({}, {}, {}, {}, {}, {'lazy': True, 'lazy_init': None, 'log_level': 'INFO', 'raise_custom_errors': False})

property default_inputs

dryrun_nodes: WorkflowNodes = <sisl.nodes.workflow.WorkflowNodes object>

static evaluate_input_node(node: Node)

Parameters:: node (Node)

classmethod final_node_key(*args) → str

Returns the key of the final (output) node of the workflow.

Return type:: str

classmethod find_node_key(node, *args) → str

Returns the identifier key of a node in this workflow

Return type:: str

classmethod from_func(func: Callable | None = None, context: dict | None = None, module: str | None = None)

Builds a node from a function.

Parameters:

func (function, optional) –
The function to be converted to a node.

If not provided, the return of this method is just a lambda function that expects the function. This is useful if you want to use this method as a decorator while also providing extra arguments (like the context argument).
context (dict, optional) – The context to be used as the default for the node class that will be created.
module (str | None)

classmethod from_node_tree(output_node: Node, workflow_name: str | None = None)

Creates a workflow class from a node.

It does so by recursively traversing the tree in the inputs direction until it finds the leaves. All the nodes found are included in the workflow. For each node, inputs that are not nodes are connected to the inputs of the workflow.

Parameters:

output_node (Node) – The final node, that should be connected to the output of the workflow.
workflow_name (str, optional) – The name of the new workflow class. If None, the name of the output node will be used.

Returns:

The newly created workflow class.

Return type:

Workflow

static function(bands_data: BandsData, Erange: Tuple[float, float] | None = None, E0: float = 0.0, E_axis: Literal['x', 'y'] = 'y', bands_range: Tuple[int, int] | None = None, spin: Literal[0, 1] | None = None, bands_style: StyleSpec = {'color': 'black', 'opacity': 1, 'width': 1}, spindown_style: StyleSpec = {'color': 'blue', 'width': 1}, gap: bool = False, gap_tol: float = 0.01, gap_color: str = 'red', gap_marker: dict = {'size': 7}, direct_gaps_only: bool = False, custom_gaps: Sequence[Dict] = [], bands_mode: Literal['line', 'scatter', 'area_line'] = 'line', groups: Sequence[OrbitalQuery] = [], fatbands_var: str = 'norm2', fatbands_mode: Literal['line', 'scatter', 'area_line'] = 'area_line', fatbands_scale: float = 1.0, backend: str = 'plotly') → Figure

Plots band structure energies showing the contribution of orbitals to each state.

Parameters:

bands_data (BandsData) – The object containing the data to plot.
Erange (Tuple[float, float] | None) – The energy range to plot. If None, the range is determined by bands_range.
E0 (float) – The energy reference.
E_axis (Literal['x', 'y']) – Axis to plot the energies.
bands_range (Tuple[int, int] | None) – The bands to plot. Only used if Erange is None. If None, the 15 bands above and below the Fermi level are plotted.
spin (Literal[0, 1] | None) – Which spin channel to display. Only meaningful for spin-polarized calculations. If None and the calculation is spin polarized, both are plotted.
bands_style (StyleSpec) – Styling attributes for bands.
spindown_style (StyleSpec) – Styling attributes for the spin down bands (if present). Any missing attribute will be taken from bands_style.
gap (bool) – Whether to display the gap.
gap_tol (float) – Tolerance in k for determining whether two gaps are the same.
gap_color (str) – Color of the gap.
gap_marker (dict) – Marker styles for the gap (as plotly marker’s styles).
direct_gaps_only (bool) – Whether to only display direct gaps.
custom_gaps (Sequence[Dict]) – List of custom gaps to display. See the showcase notebooks for examples.
bands_mode (Literal['line', 'scatter', 'area_line']) – The method used to draw the band lines.
groups (Sequence[OrbitalQuery]) – Orbital groups to plots. See showcase notebook for examples.
fatbands_var (str) – The variable to use from bands_data to determine the width of the fatbands. This variable must have as coordinates (k, band, orb, [spin]).
fatbands_mode (Literal['line', 'scatter', 'area_line']) – The method used to draw the fatbands.
fatbands_scale (float) – Factor that scales the size of all fatbands.
backend (str) – The backend to use to generate the figure.

Return type:

Figure

get()

Returns the up to date output of the workflow.

It will recompute it if necessary.

get_diagram_label(): Returns the label to be used in diagrams when displaying this node.

get_input(key: str)

Parameters:: key (str)

get_tree()

groups(*i_or_names)

Gets the groups that match your query

Parameters:

*i_or_names (str, int) –

a string (to match the name) or an integer (to match the index), You can pass as many as you want.

Note that if you have a list of them you can go like remove_group(*mylist) to spread it and use all items in your list as args.

If no query is provided, all the groups will be matched

property inputs

is_output_outdated(evaluated_inputs: Dict[str, Any])

Checks if the node needs to be ran

Parameters:: evaluated_inputs (Dict[str, Any])

property last_log: float: Last time the logs of this node were updated

logs: str

map_inputs(inputs: Dict[str, Any], func: Callable, only_nodes: bool = False, exclude: Sequence[str] = ()) → Dict[str, Any]

Maps all inputs of the node applying a given function.

It considers the args and kwargs keys.

Parameters:

inputs (Dict[str, Any]) – The inputs of the node.
func (Callable) – The function to apply to each value.
only_nodes (bool, optional) – Whether to apply the function only to nodes, by default False.
exclude (Sequence[str], optional) – The keys to exclude from the mapping. This means that these keys are returned as they are.

Return type:

Dict[str, Any]

merge(*others, **kwargs)

network = <sisl.nodes.workflow.Network object>

nodes: WorkflowNodes

classmethod plot_class_key() → str

Return type:: str

recursive_update_inputs(cls: Type | Tuple[Type, ...] | None = None, **inputs)

Updates the inputs of the node recursively.

This method updates the inputs of the node and all its children.

Parameters:

cls (Optional[Union[Type, Tuple[Type, ...]]], optional) – Only update nodes of this class. If None, update all nodes.
inputs (Dict[str, Any]) – The inputs to update.

remove_groups(*i_or_names, all=False)

Removes orbital groups.

Parameters:

*i_or_names (str, int) –

a string (to match the name) or an integer (to match the index), You can pass as many as you want.

Note that if you have a list of them you can go like remove_groups(*mylist) to spread it and use all items in your list as args

If no query is provided, all the groups will be matched

setup(*args, **kwargs): Sets up the node based on its initial inputs.

split_groups(*i_or_names, on='species', only=None, exclude=None, remove=True, clean=False, ignore_constraints=False, **kwargs)

Splits the orbital groups into multiple groups.

Parameters:

*i_or_names (str, int) –
a string (to match the name) or an integer (to match the index), You can pass as many as you want.

Note that if you have a list of them you can go like split_groups(*mylist) to spread it and use all items in your list as args

If no query is provided, all the groups will be matched
on (str, {"species", "atoms", "Z", "orbitals", "n", "l", "m", "zeta", "spin"}, or list of str) –
the parameter to split along.

Note that you can combine parameters with a “+” to split along multiple parameters at the same time. You can get the same effect also by passing a list. See examples.
only (array-like, optional) – if desired, the only values that should be plotted out of all of the values that come from the splitting.
exclude (array-like, optional) – values of the splitting that should not be plotted
remove – whether the splitted groups should be removed.
clean (boolean, optional) – whether the plot should be cleaned before drawing. If False, all the groups that come from the method will be drawn on top of what is already there.
ignore_constraints (boolean or array-like, optional) –
determines whether constraints (imposed by the group to be splitted) on the parameters that we want to split along should be taken into consideration.

If False: all constraints considered. If True: no constraints considered. If array-like: parameters contained in the list ignore their constraints.
**kwargs –
keyword arguments that go directly to each group.

This is useful to add extra filters. For example: If you had a group called “C”: plot.split_group(“C”, on=”orbitals”, spin=[0]) will split the PDOS on the different orbitals but will take only the contributions from spin up.

Examples

>>> # Split groups 0 and 1 along n and l
>>> plot.split_groups(0, 1, on="n+l")
>>> # The same, but this time even if groups 0 or 1 had defined values for "l"
>>> # just ignore them and use all possible values for l.
>>> plot.split_groups(0, 1, on="n+l", ignore_constraints=["l"])

split_orbs(on='species', only=None, exclude=None, clean=True, **kwargs)

Splits the orbitals into different groups.

Parameters:

on (str, {"species", "atoms", "Z", "orbitals", "n", "l", "m", "zeta", "spin"}, or list of str) – the parameter to split along. Note that you can combine parameters with a “+” to split along multiple parameters at the same time. You can get the same effect also by passing a list.
only (array-like, optional) – if desired, the only values that should be plotted out of all of the values that come from the splitting.
exclude (array-like, optional) – values that should not be plotted
clean (boolean, optional) – whether the plot should be cleaned before drawing. If False, all the requests that come from the method will be drawn on top of what is already there.
**kwargs –
keyword arguments that go directly to each request.

This is useful to add extra filters. For example: plot.split_orbs(on=”orbitals”, species=[“C”]) will split on the different orbitals but will take only those that belong to carbon atoms.

update_groups(*i_or_names, **kwargs)

Updates existing groups.

Parameters:

i_or_names (str or int) –
a string (to match the name) or an integer (to match the index) this will be used to find the group that you need to update.

Note that if you have a list of them you can go like update_groups(*mylist) to spread it and use all items in your list as args

If no query is provided, all the groups will be matched
**kwargs – keyword arguments containing the values that you want to update

update_inputs(**inputs): Updates the inputs of the workflow.

update_settings(*args, **kwargs)