qdk_chemistry.ui.visualization module

MCP Apps visualisation tools for qdk-chemistry.

This module conditionally registers ui:// resources backed by the JavaScript components shipped with qsharp_widgets and exposes interactive MCP tools:

  • visualize_circuit - interactive quantum-circuit diagram

  • visualize_orbital_entanglement - orbital-entanglement chord diagram

  • visualize_molecule - interactive 3D molecule viewer

  • visualize_orbitals - 3D molecule viewer with orbital isosurfaces

These tools are only registered when qsharp_widgets is installed. The tools follow the same conventions as the rest of tools.py: they accept a project_name / filename pair, load a qdk/chemistry data object, and return either an error string or a list of TextContent items with JSON data for the MCP Apps host.

qdk_chemistry.ui.visualization.load_data_object(filename, data_class)

Load a data object from either json or hdf5 file based on extension.

Parameters:

  • filename (str | PathLike[str]) – Path to a file with extension (.json or .hdf5/.h5).

  • data_class – The qdk_chemistry.data class to instantiate

Returns:

The loaded data object

Raises:

ValueError – If file extension is not supported

qdk_chemistry.ui.visualization.strip_filename_path(filename)

Return only the filename, accepting both POSIX and Windows separators.

Return type:

str

Parameters:

filename (str | Path)

qdk_chemistry.ui.visualization.validate_project(func)

Decorator to validate project before executing the function.

Validates that a project exists and exposes its absolute directory through the current execution context. The process working directory is unchanged.

It expects the decorated function to have project_name as its first parameter after self (if applicable).

Parameters:

func (TypeVar(F, bound= Callable[..., Any])) – The function to decorate. Must have project_name: str as a parameter.

Returns:

The decorated function with project validation logic, or str: a JSON string with error information.

Return type:

TypeVar(F, bound= Callable[..., Any])

Example:

@validate_project
@app.tool()
def my_function(project_name: str, other_param: int) -> str:
    # This function will only execute if project_name is valid
    return "success"
qdk_chemistry.ui.visualization.register_visualization_tools(app)[source]

Register interactive widget-based visualization tools on an MCP server.

Tools are registered only when qsharp_widgets is installed. Otherwise, this function is a no-op.

Parameters:

app – MCP server application that receives the widget resources and tools.

Return type:

None