Utilities

json_dumps() uses JSON serialization for both individual models and lists, including paths, binary files, scientific arrays, and automatic qcdata version stamps. It defaults to exclude_unset=True for compact output; pass False to include unset/default-valued fields. It accepts indent for formatting. Additional model-dump options apply consistently to both forms; mode, if supplied, must be "json".

qcdata.json_dumps

json_dumps(
    obj: BaseModel | list[BaseModel],
    exclude_unset: bool = True,
    indent: int | None = None,
    **model_dump_kwargs,
) -> str

Serialization helper for lists of pydantic objects.

Parameters:

Name	Type	Description	Default
obj	BaseModel | list[BaseModel]	The object to serialize. Either a single pydantic object or a list of pydantic objects.	required
exclude_unset	bool	Whether to exclude fields omitted during construction. Defaults to True for compact output; pass False to include all fields.	True
indent	int | None	JSON indentation, or None for compact output.	None
**model_dump_kwargs		Additional keyword arguments to pass to model_dump. Serialization always uses JSON mode.	{}

Source code in src/qcdata/utils.py

def json_dumps(
    obj: BaseModel | list[BaseModel],
    exclude_unset: bool = True,
    indent: int | None = None,
    **model_dump_kwargs,
) -> str:
    """Serialization helper for lists of pydantic objects.

    Args:
        obj: The object to serialize. Either a single pydantic object or a list of pydantic
            objects.
        exclude_unset: Whether to exclude fields omitted during construction.
            Defaults to True for compact output; pass False to include all fields.
        indent: JSON indentation, or None for compact output.
        **model_dump_kwargs: Additional keyword arguments to pass to model_dump.
            Serialization always uses JSON mode.
    """
    mode = model_dump_kwargs.pop("mode", "json")
    if mode != "json":
        raise ValueError("json_dumps requires JSON serialization mode.")

    def dump(model: BaseModel):
        return model.model_dump(
            mode="json", exclude_unset=exclude_unset, **model_dump_kwargs
        )

    payload = [dump(model) for model in obj] if isinstance(obj, list) else dump(obj)
    return json.dumps(payload, indent=indent)

qcdata.to_multi_xyz

to_multi_xyz(structures: Iterable[Structure]) -> str

Create a multi-structure XYZ string from a list of structures.

Parameters:

Name	Type	Description	Default
structures	Iterable[Structure]	An Iterable of Structure objects.	required

Returns:

Type	Description
str	The multi-structure XYZ string.

Source code in src/qcdata/models/utils.py

def to_multi_xyz(structures: Iterable["Structure"]) -> str:
    """Create a multi-structure XYZ string from a list of structures.

    Args:
        structures: An Iterable of Structure objects.

    Returns:
        The multi-structure XYZ string.
    """
    return "".join(struct.to_xyz() for struct in structures)