The sdds Python module provides a high-level interface for creating, manipulating, and reading Self Describing Data Sets (SDDS) files, a file protocol designed for storing and transferring scientific data.
- Read and Write SDDS files in ASCII and binary formats.
- Support for all SDDS data types: parameters, arrays, and columns.
- Define and manipulate data with ease.
- Multi-page data handling for advanced use cases.
- Includes mostly compatible read() and write() functions similar to the PyLHC sdds module. Unlike the PyLHC version, this module works with multi-page SDDS files and with column data.
- Python 3.8 or higher
- An SDDS-compatible environment with the necessary C library dependencies (already integrated into this module).
You can install the sdds module directly using pip or conda:
python -m pip install soliday.sddsconda install soliday::sddsBelow is an example of how to create an SDDS file with parameters, columns, and arrays.
import sdds
def main():
# Initialize the SDDS object
sdds_obj = sdds.SDDS()
# Specify the name of the output SDDS file
output_file = "output_all_data_types.sdds"
# Set the description of the SDDS file with a brief text and detailed contents
sdds_obj.setDescription(
"Example output file for demonstration purposes",
"Includes parameters, columns, and arrays for every supported datatype."
)
# Define parameters for all supported SDDS data types
sdds_obj.defineSimpleParameter("param_short", sdds.SDDS_SHORT)
sdds_obj.defineSimpleParameter("param_ushort", sdds.SDDS_USHORT)
sdds_obj.defineSimpleParameter("param_long", sdds.SDDS_LONG)
sdds_obj.defineSimpleParameter("param_ulong", sdds.SDDS_ULONG)
sdds_obj.defineSimpleParameter("param_long64", sdds.SDDS_LONG64)
sdds_obj.defineSimpleParameter("param_ulong64", sdds.SDDS_ULONG64)
sdds_obj.defineSimpleParameter("param_float", sdds.SDDS_FLOAT)
sdds_obj.defineSimpleParameter("param_double", sdds.SDDS_DOUBLE)
sdds_obj.defineSimpleParameter("param_string", sdds.SDDS_STRING)
sdds_obj.defineSimpleParameter("param_character", sdds.SDDS_CHARACTER)
# Define columns for all supported SDDS data types
sdds_obj.defineSimpleColumn("col_short", sdds.SDDS_SHORT)
sdds_obj.defineSimpleColumn("col_ushort", sdds.SDDS_USHORT)
sdds_obj.defineSimpleColumn("col_long", sdds.SDDS_LONG)
sdds_obj.defineSimpleColumn("col_ulong", sdds.SDDS_ULONG)
sdds_obj.defineSimpleColumn("col_long64", sdds.SDDS_LONG64)
sdds_obj.defineSimpleColumn("col_ulong64", sdds.SDDS_ULONG64)
sdds_obj.defineSimpleColumn("col_float", sdds.SDDS_FLOAT)
sdds_obj.defineSimpleColumn("col_double", sdds.SDDS_DOUBLE)
sdds_obj.defineSimpleColumn("col_string", sdds.SDDS_STRING)
sdds_obj.defineSimpleColumn("col_character", sdds.SDDS_CHARACTER)
# Define arrays for all supported SDDS data types
# The third parameter specifies the dimensionality of the array
sdds_obj.defineSimpleArray("array_short", sdds.SDDS_SHORT, 1)
sdds_obj.defineSimpleArray("array_ushort", sdds.SDDS_USHORT, 1)
sdds_obj.defineSimpleArray("array_long", sdds.SDDS_LONG, 2)
sdds_obj.defineSimpleArray("array_ulong", sdds.SDDS_ULONG, 1)
sdds_obj.defineSimpleArray("array_long64", sdds.SDDS_LONG64, 1)
sdds_obj.defineSimpleArray("array_ulong64", sdds.SDDS_ULONG64, 1)
sdds_obj.defineSimpleArray("array_float", sdds.SDDS_FLOAT, 1)
sdds_obj.defineSimpleArray("array_double", sdds.SDDS_DOUBLE, 1)
sdds_obj.defineSimpleArray("array_string", sdds.SDDS_STRING, 1)
sdds_obj.defineSimpleArray("array_character", sdds.SDDS_CHARACTER, 1)
# -------------------------
# Populate Page 1 with Data
# -------------------------
# Set parameter values for Page 1
sdds_obj.setParameterValue("param_short", 1, page=1)
sdds_obj.setParameterValue("param_ushort", 2, page=1)
sdds_obj.setParameterValue("param_long", 3, page=1)
sdds_obj.setParameterValue("param_ulong", 4, page=1)
sdds_obj.setParameterValue("param_long64", 5, page=1)
sdds_obj.setParameterValue("param_ulong64", 6, page=1)
sdds_obj.setParameterValue("param_float", 7.7, page=1)
sdds_obj.setParameterValue("param_double", 8.8, page=1)
sdds_obj.setParameterValue("param_string", "Page 1 String", page=1)
sdds_obj.setParameterValue("param_character", "A", page=1)
# Define column data for Page 1
columns_page1 = {
"col_short": [1, 2],
"col_ushort": [3, 4],
"col_long": [5, 6],
"col_ulong": [7, 8],
"col_long64": [9, 10],
"col_ulong64": [11, 12],
"col_float": [13.1, 14.2],
"col_double": [15.3, 16.4],
"col_string": ["String1", "String2"],
"col_character": ["X", "Y"],
}
# Populate column data for Page 1
for col_name, col_data in columns_page1.items():
sdds_obj.setColumnValueList(col_name, col_data, page=1)
# Define array data for Page 1 (one-dimensional arrays)
arrays_page1_1d = {
"array_short": [1, 2, 3],
"array_ushort": [4, 5, 6],
"array_ulong": [10, 11, 12],
"array_long64": [13, 14, 15],
"array_ulong64": [16, 17, 18],
"array_float": [19.1, 20.2, 21.3],
"array_double": [22.4, 23.5, 24.6],
"array_string": ["Array1", "Array2", "Array3"],
"array_character": ["M", "N", "O"],
}
# Populate one-dimensional array data for Page 1
for array_name, array_data in arrays_page1_1d.items():
sdds_obj.setArrayValueList(array_name, array_data, [3], page=1)
# Define array data for Page 1 (two-dimensional array)
arrays_page1_2d = {
"array_long": [7, 8, 9, 17, 18, 19],
}
# Populate two-dimensional array data for Page 1
for array_name, array_data in arrays_page1_2d.items():
sdds_obj.setArrayValueList(array_name, array_data, [2, 3], page=1)
# -------------------------
# Populate Page 2 with Data
# -------------------------
# Set parameter values for Page 2
sdds_obj.setParameterValue("param_short", 10, page=2)
sdds_obj.setParameterValue("param_ushort", 20, page=2)
sdds_obj.setParameterValue("param_long", 30, page=2)
sdds_obj.setParameterValue("param_ulong", 40, page=2)
sdds_obj.setParameterValue("param_long64", 50, page=2)
sdds_obj.setParameterValue("param_ulong64", 60, page=2)
sdds_obj.setParameterValue("param_float", 70.7, page=2)
sdds_obj.setParameterValue("param_double", 80.8, page=2)
sdds_obj.setParameterValue("param_string", "Page 2 String", page=2)
sdds_obj.setParameterValue("param_character", "B", page=2)
# Define column data for Page 2
columns_page2 = {
"col_short": [21, 22],
"col_ushort": [23, 24],
"col_long": [25, 26],
"col_ulong": [27, 28],
"col_long64": [29, 30],
"col_ulong64": [31, 32],
"col_float": [33.1, 34.2],
"col_double": [35.3, 36.4],
"col_string": ["String3", "String4"],
"col_character": ["Z", "W"],
}
# Populate column data for Page 2
for col_name, col_data in columns_page2.items():
sdds_obj.setColumnValueList(col_name, col_data, page=2)
# Define array data for Page 2 (one-dimensional arrays)
arrays_page2_1d = {
"array_short": [101, 102, 103],
"array_ushort": [104, 105, 106],
"array_ulong": [110, 111, 112],
"array_long64": [113, 114, 115],
"array_ulong64": [116, 117, 118],
"array_float": [119.1, 120.2, 121.3],
"array_double": [122.4, 123.5, 124.6],
"array_string": ["Array4", "Array5", "Array6"],
"array_character": ["P", "Q", "R"],
}
# Populate one-dimensional array data for Page 2
for array_name, array_data in arrays_page2_1d.items():
sdds_obj.setArrayValueList(array_name, array_data, [3], page=2)
# Define array data for Page 2 (two-dimensional array)
arrays_page2_2d = {
"array_long": [107, 108, 109, 207, 208, 209],
}
# Populate two-dimensional array data for Page 2
for array_name, array_data in arrays_page2_2d.items():
sdds_obj.setArrayValueList(array_name, array_data, [2, 3], page=2)
# -------------------------
# Save the SDDS File
# -------------------------
# Save all the defined data into the specified SDDS file
sdds_obj.save(output_file)
# Opitonally delete the SDDS object
del sdds_obj
if __name__ == "__main__":
main()Here’s how to read and inspect an SDDS file:
import sdds
def main():
# Specify the input SDDS file.
input_file = "output_all_data_types.sdds"
# Load the SDDS file into the SDDS object
sdds_obj = sdds.load(input_file)
# Determine and display the file mode: Binary or ASCII
if sdds_obj.mode == sdds.SDDS_BINARY:
print("SDDS file mode: SDDS_BINARY")
else:
print("SDDS file mode: SDDS_ASCII")
# Display the description text if available
if sdds_obj.description[0]:
print(f"SDDS file description text: {sdds_obj.description[0]}")
# Display additional description contents if available
if sdds_obj.description[1]:
print(f"SDDS file description contents: {sdds_obj.description[1]}")
# Check and print parameter definitions if any are present
if sdds_obj.parameterName:
print("\nParameters:")
for i, definition in enumerate(sdds_obj.parameterDefinition):
name = sdds_obj.parameterName[i]
datatype = sdds.sdds_data_type_to_string(definition[4])
units = definition[1]
description = definition[2]
print(f" {name}")
print(f" Datatype: {datatype}", end="")
if units:
print(f", Units: {units}", end="")
if description:
print(f", Description: {description}", end="")
print("") # Newline for readability
# Check and print array definitions if any are present
if sdds_obj.arrayName:
print("\nArrays:")
for i, definition in enumerate(sdds_obj.arrayDefinition):
name = sdds_obj.arrayName[i]
datatype = sdds.sdds_data_type_to_string(definition[5])
units = definition[1]
description = definition[2]
dimensions = definition[7]
print(f" {name}")
print(f" Datatype: {datatype}, Dimensions: {dimensions}", end="")
if units:
print(f", Units: {units}", end="")
if description:
print(f", Description: {description}", end="")
print("") # Newline for readability
# Check and print column definitions if any are present
if sdds_obj.columnName:
print("\nColumns:")
for i, definition in enumerate(sdds_obj.columnDefinition):
name = sdds_obj.columnName[i]
datatype = sdds.sdds_data_type_to_string(definition[4])
units = definition[1]
description = definition[2]
print(f" {name}")
print(f" Datatype: {datatype}", end="")
if units:
print(f", Units: {units}", end="")
if description:
print(f", Description: {description}", end="")
print("") # Newline for readability
# Iterate through each loaded page and display parameter, array, and column data
for page in range(sdds_obj.loaded_pages):
print(f"\nPage: {page + 1}")
# Display parameter data for the current page
for i, name in enumerate(sdds_obj.parameterName):
value = sdds_obj.parameterData[i][page]
print(f" Parameter '{name}': {value}")
# Display array data for the current page
for i, name in enumerate(sdds_obj.arrayName):
value = sdds_obj.arrayData[i][page]
print(f" Array '{name}': {value}")
# Display column data for the current page
for i, name in enumerate(sdds_obj.columnName):
value = sdds_obj.columnData[i][page]
print(f" Column '{name}': {value}")
# Opitonally delete the SDDS object
del sdds_obj
if __name__ == "__main__":
main()For detailed documentation, examples, and API references, visit the SDDS Python Module Documentation.
This project is licensed under the SDDS Toolkit License. See the LICENSE file for details.
For questions or support, email soliday@anl.gov