FemzipAPI

FemzipAPI contains wrapper functions around the femzip library.

`api: CDLL` `property`

Returns the loaded, shared object library of the native interface

Returns:

Name	Type	Description
`shared_object_lib`	`CDLL`	Loaded shared object library.

`close_current_file()`

Closes the current file handle(use not recommended)

Notes

Closes a currently opened file by the API. There
is no arg because femzip can process only one file
at a time.
This can also be used in case of bugs.

Examples:

>>> api.close_current_file()

`copy_struct(src, dest)` `staticmethod`

Copies all fields from src struct to dest

Parameters:

Name	Type	Description	Default
`src`	`Structure`	src struct	required
`src`	`Structure`	destination struct	required

Examples:

>>> err1 = FemzipError()
>>> err1.ier = -1
>>> err1.msg = b"Oops"
>>> err2 = FemzipError()
>>> api.copy_struct(err1, err2)
>>> err2.ier
-1
>>> err2.msg
b'Oops'

`get_buffer_info(filepath)`

Get the dimensions of the buffers for femzip

Parameters:

Name	Type	Description	Default
`filepath`	`str`	path to femzip file	required

Returns:

Name	Type	Description
`buffer_info`	`FemzipBufferInfo`	c struct with infos about the memory required by femzip

Examples:

>>> # read memory demand info first
>>> buffer_info = api.get_buffer_info(filepath)
>>> # buffer info is a c struct, but we can print it
>>> api.struct_to_dict(buffer_info)
{'n_timesteps': 12,
'timesteps': <lasso.femzip.femzip_api.LP_c_float object at 0x0000028A8F6B21C0>,
'size_geometry': 537125, 'size_state': 1462902, 'size_displacement': 147716,
'size_activity': 47385, 'size_post': 1266356, 'size_titles': 1448}
>>> for i_timestep in range(buffer_info.n_timesteps):
>>>     print(buffer_info.timesteps[i_timestep])
0.0
0.9998100399971008
1.9998900890350342
2.9999701976776123
3.9997801780700684

`get_femzip_status()`

Check the status of the femzip api

Returns:

Name	Type	Description
`femzip_status`	`FemzipAPIStatus`	c struct with info about femzip API

Notes

This reports whether a file is currently
opened and how far it was processed. This
internal state is used to avoid internal
conflicts and crashes, thus is useful for
debugging.

Examples:

>>> print(api.struct_to_dict(api.get_femzip_status()))
{'is_file_open': 0, 'is_geometry_read': 0, 'is_states_open': 0,
'i_timestep_state': -1, 'i_timestep_activity': -1}

`get_file_metadata(filepath)`

Get infos about the femzip variables in the file

Parameters:

Name	Type	Description	Default
`filepath`	`str`	path to femzip file	required

Returns:

Name	Type	Description
`file_metadata`	`FemzipFileMetadata`	c struct with infos about the femzip file

Notes

This is for direct interaction with the C-API, thus should
not be used by users.

Examples:

>>> file_metadata = api.get_file_metadata("path/to/d3plot.fz")
>>> # print general internals
>>> api.struct_to_dict(file_metadata)
{'version_zip': 605.0, 'activity_flag': 1, 'number_of_variables': 535, ...}

>>> # We can iterate the variable names contained in the file
>>> print(
    [file_metadata.variable_infos[i_var].name.decode("utf8").strip()
    for i_var in range(file_metadata.number_of_variables)]
)
['global', 'Parts: Energies and others', 'coordinates', 'velocities', ...]

`get_part_titles(filepath, buffer_info=None)`

Get the part title section

Parameters:

Name	Type	Description	Default
`filepath`	`str`	path to femzip file	required
`buffer_info`	`Union[None, FemzipBufferInfo]`	buffer info if previously fetched	`None`

Returns:

Name	Type	Description
`mview`	`memoryview`	memory of the part title section

`has_femunziplib_license()`

Checks whether the extended libraries are available

Returns:

Name	Type	Description
`has_license`	`bool`

Examples:

>>> api.has_femunziplib_license()
False

`is_femunzip_version_ok(filepath)`

Checks if the femunzip version can be handled

Parameters:

Name	Type	Description	Default
`filepath`	`str`	path to the femzpi file	required

Returns:

Name	Type	Description
`version_ok`	`bool`

Examples:

>>> api.is_femunzip_version_ok("path/to/d3plot.fz")
True

`is_sidact_file(filepath)`

Tests if a filepath points at a sidact file

Parameters:

Name	Type	Description	Default
`filepath`	`str`		required

Returns:

Name	Type	Description
`is_sidact_file`	`bool`

Examples:

>>> api.is_sidact_file("path/to/d3plot.fz")
True
>>> api.is_sidact_file("path/to/d3plot")
False
>>> api.is_sidact_file("path/to/non/existing/file")
False

`load_dynamic_library(path)` `staticmethod`

Load a library and check for correct execution

Parameters:

Name	Type	Description	Default
`path`	`str`	path to the library	required

Returns:

Name	Type	Description
`library`	`CDLL`	loaded library

`read_geometry(filepath, buffer_info=None, close_file=True)`

Read the geometry buffer from femzip

Parameters:

Name	Type	Description	Default
`filepath`	`str`	path to femzpi file	required
`buffer_info`	`Union[FemzipBufferInfo, None]`	struct with info regarding required memory for femzip	`None`
`close_file`	`bool`	it is useful to leave the file open if states are processed right afterwards	`True`

Returns:

Name	Type	Description
`buffer`	`memoryview`	memoryview of buffer

Notes

If the file isn't closed appropriately bugs and crashes
might occur.

Examples:

>>> mview = api.read_geometry(filepath, buffer_info)

`read_single_state(i_timestep, buffer_info, state_buffer=None)`

Read a single state

Parameters:

Name	Type	Description	Default
`i_timestep`	`int`	timestep to be read	required
`buffer_info`	`FemzipBufferInfo`	infos about buffer sizes	required
`state_buffer`	`Union[None, memoryview]`	buffer in which the states are stored	`None`

Notes

It is unclear to us why the state buffer needs to be given
in order to terminate state reading.

Examples:

>>> # get info about required memory
>>> buffer_info = api.get_buffer_info(filepath)

>>> # first read geometry and leave file open
>>> mview_geom = api.read_geometry(filepath, buffer_info, False)

>>> # now read a state
>>> mview_state = api.read_single_state(0, buffer_info=buffer_info)

>>> # close file
>>> api.close_current_file()

`read_state_deletion_info(buffer_info, state_filter=None)`

Get information which elements are alive

Parameters:

Name	Type	Description	Default
`buffer_info`	`FemzipBufferInfo`	infos about buffer sizes	required
`state_filter`	`Union[Set[int], None]`	usable to read only specific states	`None`

Notes

The `buffer` must have the size of at least
`buffer_info.size_activity`.

Examples:

>>> # get info about required memory
>>> buffer_info = api.get_buffer_info(filepath)

>>> # first read geometry and leave file open!
>>> mview_geom = api.read_geometry(filepath, buffer_info, False)

>>> # now read deletion info
>>> array_deletion = api.read_state_activity(buffer_info)

>>> # close file
>>> api.close_current_file()

`read_states(filepath, buffer_info=None, state_filter=None)`

Reads all femzip state information

Parameters:

Name	Type	Description	Default
`filepath`	`str`	path to femzip file	required
`buffer_info`	`Union[FemzipBufferInfo, None]`	struct with info regarding required memory for femzip	`None`
`state_filter`	`Union[Set[int], None]`	usable to load only specific states	`None`

Returns:

Name	Type	Description
`buffer`	`memoryview`	buffer containing all state data

Examples:

>>> buffer_info = api.get_buffer_info("path/to/d3plot.fz")
>>> array_states = api.read_states("path/to/d3plot.fz", buffer_info)

`read_variables(file_metadata, n_parts, n_rigid_walls, n_rigid_wall_vars, n_airbag_particles, n_airbags, state_filter=None)`

Read specific variables from Femzip

Parameters:

Name	Type	Description	Default
`file_metadata`	`FemzipFileMetadata`	metadata of file including which variables to read	required
`n_parts`	`int`	number of parts in the file	required
`n_rigid_walls`	`int`	number of rigid walls	required
`n_rigid_wall_vars`	`int`	number of rigid wall variables	required
`n_airbag_particles`	`int`	number of airbag particles in the file	required
`n_airbags`	`int`		required
`state_filter`	`Union[Set[int], None]`	used to read specific arrays	`None`

Returns:

Name	Type	Description
`arrays`	`dict`	dictionary with d3plot arrays

`struct_to_dict(struct)` `staticmethod`

Converts a ctypes struct into a dict

Parameters:

Name	Type	Description	Default
`struct`	`Structure`		required

Returns:

Name	Type	Description
`fields`	`Dict[str, Any]`	struct as dict

Examples:

>>> api.struct_to_dict(api.get_femzip_status())
{'is_file_open': 1, 'is_geometry_read': 1, 'is_states_open': 0,
'i_timestep_state': -1, 'i_timestep_activity': -1}

FemzipAPI

api: CDLL property

close_current_file()

Notes

copy_struct(src, dest) staticmethod

get_buffer_info(filepath)

get_femzip_status()

Notes

get_file_metadata(filepath)

Notes

get_part_titles(filepath, buffer_info=None)

has_femunziplib_license()

is_femunzip_version_ok(filepath)

is_sidact_file(filepath)

load_dynamic_library(path) staticmethod

read_geometry(filepath, buffer_info=None, close_file=True)

Notes

read_single_state(i_timestep, buffer_info, state_buffer=None)

Notes

read_state_deletion_info(buffer_info, state_filter=None)

Notes

read_states(filepath, buffer_info=None, state_filter=None)

read_variables(file_metadata, n_parts, n_rigid_walls, n_rigid_wall_vars, n_airbag_particles, n_airbags, state_filter=None)

struct_to_dict(struct) staticmethod

`api: CDLL` `property`

`close_current_file()`

`copy_struct(src, dest)` `staticmethod`

`get_buffer_info(filepath)`

`get_femzip_status()`

`get_file_metadata(filepath)`

`get_part_titles(filepath, buffer_info=None)`

`has_femunziplib_license()`

`is_femunzip_version_ok(filepath)`

`is_sidact_file(filepath)`

`load_dynamic_library(path)` `staticmethod`

`read_geometry(filepath, buffer_info=None, close_file=True)`

`read_single_state(i_timestep, buffer_info, state_buffer=None)`

`read_state_deletion_info(buffer_info, state_filter=None)`

`read_states(filepath, buffer_info=None, state_filter=None)`

`read_variables(file_metadata, n_parts, n_rigid_walls, n_rigid_wall_vars, n_airbag_particles, n_airbags, state_filter=None)`

`struct_to_dict(struct)` `staticmethod`