Simulation data#

Simulation data files are used to represent sequences of values:

  • they are the outputs of simulation jobs;

  • they can be used in test harnesses, in data source and oracle blocks, to be used respectively as inputs and expected values.

This library allows to read and edit simulation data files. Look for simulation data in Scade One documentation.

Covered features#

  • Support of none values, meaning that the value is not defined at a given cycle:

    • Stimuli operator: a value must be defined at first cycle, for next steps the none type means that a previous value is held.

    • Simulator trace: a none value means that the variable clock is false.

  • Support of all Swan types, imported types (stored as a byte array) and combinations of them (native support of Variants & Groups).

    • Data support: structure, table (when the table size is a static constant), enum, string.

    • Limitations: partial data is not supported. All values of a complex type must be given.

  • The variables are organized as a tree of <scope>/<scope>/…/<variable>, each scope and variable has an optional Swan kind: sensors, inputs, outputs, probes, assume, guarantee and so on.

  • Possibility to specify a repetition of a signal or part of it.

  • Possibility to open an existing file for modification: elements, types and values.

Design principles#

  • A file of binary format does not allow a value conversion to or from string.

  • The values are stored as their binary representation in memory: no structured representation of composite values.

  • The values sequences are compressed using the zlib data-compression library.

  • The file size has no limit (more than 4 GB): use of 64 bits positions and C APIs for seek in file.

  • The entire file content is not loaded in memory when opening: the data is read in file only on demand.

  • The file content is not entirely rewritten on disk when closing: incremental read and write operations.

Performance#

  • Appending values to an element: no need to read all the values before appending and use of a write cache.

  • Updating element: no move of significant data in file.

Example using API simulation data#

import ansys.scadeone.core.svc.simdata as sd

f = sd.create_file("mySimDataFile.sd") # creates a new simulation data file

t_struct1 = sd.create_struct_type([("f1", sd.Bool), ("f2", sd.Int32)], "p1::tStruct1") # creates a new structure type
e_struct1 = f.add_element("eStruct1", t_struct1) # adds an element to the file
clock1 = False

for i in range(10): # number of cycles
    clock1 = not clock1
    e_struct1.append_value([clock1, i + 14]) # adds values to the element

f.close() # closes the file

Simulation data file preview command line#

The pyscadeone Command line interface is used, in combination with the simdata and -show arguments, to preview the content of a data file with .SD extension in a text editor, without opening the Scade One tool or Signal Editor.

# View content of a .SD file as a text
pyscadeone simdata --show some_file.sd > some_file.txt
notepad some_file.txt # opens the file in notepad, or vi editor and so on

High-level API#

class ansys.scadeone.core.svc.simdata.csd.Element(file: FileBase, elem_id: int, parent: ElementBase | None, name: str, sd_type: Type | None, kind: SdeKind)#

Bases: ElementBase

Class for simdata elements

add_child_element(name: str, sd_type: Type | None = None, kind: SdeKind = SdeKind.NONE) → ElementBase#

Add a child to element

Parameters:
namestr

child element name

sd_typeType, optional

child element type

kindElementKind, optional

child element kind

Returns:
ElementBase

Created child element

remove_child_element(element: Element) → None#

Remove a child from element

Parameters:
elementElement

element to remove

Raises:
ScadeOneException

child could not be removed

append_value(py_value: Any) → None#

Add a value to an element or appends to the last sequence of values if any. This method shall NOT be used to add a single value after a multiple cycles sequence as it would also be repeated alongside the previous sequence. Prefer using append_values([py_value]) instead in such case.

Parameters:
py_valueAny

value that has a type corresponding to the element

Raises:
ScadeOneException

value is invalid or could not be added

append_nones(count: int) → None#

Add a sequence of none values to an element (undefined cycle values)

Parameters:
countint

number of Nones to add

Raises:
ScadeOneException

cannot create or append nones sequence

append_values(py_values: List[Any], repeat_factor: int | None = 1) → None#

Create a new sequence of one or multiple values. Do not use repeat factor for array and structure types. Do not use this for structure or array types that already have any value, use append_value() instead in such case.

Parameters:
py_valuesList[Any]

list of value(s) to add

repeat_factorOptional[int], optional

number of times to add, by default 1 (no repeat), do not use with non scalar values

Raises:
ScadeOneException

Invalid repeat, none contained in values, invalid values, cannot create or append values sequence, used repeat factor for array or structure types

read_values(start: int | None = None, n: int | None = None) → Iterator[Value]#

Read element values

Parameters:
startint, optional

start index for reading, beginning if not specified

nint, optional

number of values to read, runs until end if not specified

Yields:
Iterator[Value]

each value read

clear_values() → None#

Clear all values of element

Raises:
ScadeOneException

values could not be cleared

class ansys.scadeone.core.svc.simdata.csd.File(file_id: int)#

Bases: FileBase

Simdata files class

add_element(name: str, sd_type: Type | None = None, kind: SdeKind = SdeKind.NONE) → ElementBase#

Create and add an element to file

Parameters:
namestr

element name

sd_typeType, optional

type of element

kindElementKind, optional

kind of element

Returns:
ElementBase

The new element that was added to file

remove_element(element: Element) → None#

Delete an element from file

Parameters:
elementElement

element to delete

Raises:
ScadeOneException

element could not be found or deleted

get_version() → str#

Get the file version

Returns:
str

Version number

close() → None#

Close a file

Raises:
ScadeOneException

Could not close file or file was not opened

ansys.scadeone.core.svc.simdata.csd.open_file(file_path: str) → FileBase#

Open a simdata file

Parameters:
file_pathstr

path of the file

Returns:
FileBase

The opened file

Raises:
ScadeOneException

file could not be opened

ansys.scadeone.core.svc.simdata.csd.create_file(file_path: str) → FileBase#

Create a simdata file

Parameters:
file_pathstr

path of the file

Returns:
FileBase

The created file

Raises:
ScadeOneException

file could not be created

ansys.scadeone.core.svc.simdata.csd.create_struct_type(fields: List[Tuple], name: str = '') → StructType#

Create a structure type

Parameters:
fieldsList[Tuple]

all fields of the structure

namestr, optional

structure name

Returns:
StructType

The created structure type

Raises:
ScadeOneException

structure type could not be created, arguments are invalid, or field names duplicate

ansys.scadeone.core.svc.simdata.csd.create_array_type(base_type: Type, dims: List[int], name: str = '') → ArrayType#

Create a multi dimensional array type

Parameters:
base_typeType

type of array

dimsList[int]

array dimensions

namestr, optional

array name

Returns:
ArrayType

Created array type

Raises:
ScadeOneException

array type could not be created, argument error or none type passed

ansys.scadeone.core.svc.simdata.csd.create_enum_type(values: List[str], name: str = '') → EnumType#

Create an enumeration type

Parameters:
valuesList[str]

values of the enumeration type

namestr, optional

name of enumeration type

Returns:
EnumType

Created enumeration type

Raises:
ScadeOneException

could not create enumeration type, create a value of passed argument or invalid arguments in creation

ansys.scadeone.core.svc.simdata.csd.create_variant_type(constructors: List[Tuple], name: str = '') → VariantType#

Create a variant type

Parameters:
constructorsList[Tuple]

constructors of the variant type

namestr, optional

name of variant type

Returns:
VariantType

Created variant type

Raises:
ScadeOneException

variant type could not be created, invalid arguments or duplicate constructor names

ansys.scadeone.core.svc.simdata.csd.create_imported_type(mem_size: int, name: str = '') → ImportedType#

Create an imported type

Parameters:
mem_sizeint

memory size

namestr, optional

imported type name

Returns:
ImportedType

Created imported type

Raises:
ScadeOneException

could not create imported type, argument type error or argument type error

Type definitions#

Predefined swan types that shall be used for creation of simple elements or user types definitions

Id

Type

0

Char

3

Bool

4

Int8

5

Int16

6

Int32

7

Int64

8

UInt8

9

UInt32

10

UInt32

11

UInt64

12

Float32

13

Float64

Using a predefined type (float 32 here) for new element and custom user type

import ansys.scadeone.core.svc.simdata as sd

my_file = sd.create_file("mySimDataFile.sd")

my_element1 = my_file.add_element("myElement", sd.Float32)

my_array_type = sd.create_array_type(sd.Float32, [3, 4], "my2DArrayType")
my_element2 = my_file.add_element("my2DArrayElement", my_array_type)
class ansys.scadeone.core.svc.simdata.defs.ArrayType(type_id: int, base_type: Type, dims: List[int], name: str = '')#

Bases: Type

Multidimensional array type

class ansys.scadeone.core.svc.simdata.defs.EnumType(type_id: int, base_type: PredefinedType, values: List[EnumTypeValue], name: str = '')#

Bases: Type

Enumeration type defined with enumeration values

class ansys.scadeone.core.svc.simdata.defs.EnumTypeValue(name: str, int_value: int)#

Bases: object

Enumeration type value

class ansys.scadeone.core.svc.simdata.defs.EnumValue(name: str)#

Bases: Value

Values for enumeration types

class ansys.scadeone.core.svc.simdata.defs.ImportedType(type_id: int, mem_size: int, vsize: bool = False, pfn_vsize_get_bytes_size: ~ctypes.CFUNCTYPE.<locals>.CFunctionType | None = None, pfn_vsize_to_bytes: ~ctypes.CFUNCTYPE.<locals>.CFunctionType | None = None, name: str = '')#

Bases: Type

Imported Types (stored as byte arrays)

class ansys.scadeone.core.svc.simdata.defs.ImportedValue(bytes_data)#

Bases: Value

Values for imported types

class ansys.scadeone.core.svc.simdata.defs.ListValue(values: List[Value])#

Bases: Value

Values for list types

class ansys.scadeone.core.svc.simdata.defs.NoneValue#

Bases: Value

None Values

class ansys.scadeone.core.svc.simdata.defs.PredefinedBoolValue(value: c_ubyte)#

Bases: PredefinedValue

Values for predefined type boolean

class ansys.scadeone.core.svc.simdata.defs.PredefinedCharValue(value: c_ubyte)#

Bases: PredefinedValue

Values for predefined type char

class ansys.scadeone.core.svc.simdata.defs.PredefinedFloat32Value(value: c_float)#

Bases: PredefinedValue

Values for predefined type float 32

class ansys.scadeone.core.svc.simdata.defs.PredefinedFloat64Value(value: c_double)#

Bases: PredefinedValue

Values for predefined type float 64

class ansys.scadeone.core.svc.simdata.defs.PredefinedInt16Value(value: c_short)#

Bases: PredefinedValue

Values for predefined type int 16

class ansys.scadeone.core.svc.simdata.defs.PredefinedInt32Value(value: c_long)#

Bases: PredefinedValue

Values for predefined type int 32

class ansys.scadeone.core.svc.simdata.defs.PredefinedInt64Value(value: c_longlong)#

Bases: PredefinedValue

Values for predefined type int 64

class ansys.scadeone.core.svc.simdata.defs.PredefinedInt8Value(value: c_byte)#

Bases: PredefinedValue

Values for predefined type int 8

class ansys.scadeone.core.svc.simdata.defs.PredefinedType(type_id: int)#

Bases: Type

Predefined Swan types are not stored in file. They have hard-coded identifiers that can be used in user types definitions.

class ansys.scadeone.core.svc.simdata.defs.PredefinedUInt16Value(value: c_ushort)#

Bases: PredefinedValue

Values for predefined type unsigned int 16

class ansys.scadeone.core.svc.simdata.defs.PredefinedUInt32Value(value: c_ulong)#

Bases: PredefinedValue

Values for predefined type unsigned int 32

class ansys.scadeone.core.svc.simdata.defs.PredefinedUInt64Value(value: c_ulonglong)#

Bases: PredefinedValue

Values for predefined type unsigned int 64

class ansys.scadeone.core.svc.simdata.defs.PredefinedUInt8Value(value: c_ubyte)#

Bases: PredefinedValue

Values for predefined type unsigned int 8

class ansys.scadeone.core.svc.simdata.defs.PredefinedValue#

Bases: Value

Values for predefined Swan Types

class ansys.scadeone.core.svc.simdata.defs.StructType(type_id: int, fields: List[StructTypeField], name: str = '')#

Bases: Type

Structure type defined with structure type fields

class ansys.scadeone.core.svc.simdata.defs.StructTypeField(name: str, offset: int, sd_type: Type)#

Bases: object

Structure type’s fields

class ansys.scadeone.core.svc.simdata.defs.Type(type_id: int, name: str = '')#

Bases: object

Represents an abstract data type.

class ansys.scadeone.core.svc.simdata.defs.UntypedVariantConstructorValue#

Bases: Value

No value to return for untyped variant constructor

class ansys.scadeone.core.svc.simdata.defs.Value#

Bases: object

Interface for all element types values that shall provide a readable string representation

class ansys.scadeone.core.svc.simdata.defs.VariantType(type_id: int, constructors: List[VariantTypeConstructor], name: str = '')#

Bases: Type

Variant type defined with variant type constructors

class ansys.scadeone.core.svc.simdata.defs.VariantTypeConstructor(name: str, value_type: Type | None)#

Bases: object

Variant type constructor

class ansys.scadeone.core.svc.simdata.defs.VariantValue(name: str, value: Value | None)#

Bases: Value

Values for variant types

On this page
Show Source