piel

piel#

Top-level package for piel.

Submodules#

Attributes#

rp

PathTypes

ModuleType

__author__

__email__

__version__

Functions#

check_path_exists(→ bool)

Checks if a directory exists.

check_example_design(→ bool)

We copy the example simple_design from docs to the /foss/designs in the iic-osic-tools environment.

copy_source_folder(→ None)

Copies the files from a source_directory to a target_directory

copy_example_design(→ None)

We copy the example simple_design from docs to the /foss/designs in the iic-osic-tools environment.

create_new_directory(→ bool)

Creates a new directory.

create_piel_home_directory(→ None)

Creates the piel home directory.

delete_path(→ None)

Deletes a path.

delete_path_list_in_directory(→ None)

Deletes a list of files in a directory.

get_files_recursively_in_directory(path[, extension])

Returns a list of files in a directory.

get_top_level_script_directory(→ pathlib.Path)

Attempts to return the top-level script directory when this file is run,

get_id_map_directory_dictionary(path_list, target_prefix)

Returns a dictionary of ids to directories.

list_prefix_match_directories(output_directory, ...)

Returns a list of directories that match a prefix.

permit_directory_all(→ None)

Permits a directory to be read, written and executed. Use with care as it can be a source for security issues.

permit_script_execution(→ None)

Permits the execution of a script.

read_json(→ dict)

Reads a JSON file.

rename_file(→ None)

Renames a file.

rename_files_in_directory(→ None)

Renames all files in a directory.

replace_string_in_file(file_path, match_string, ...)

Replaces a string in a file.

replace_string_in_directory_files(target_directory, ...)

Replaces a string in all files in a directory.

return_path(→ pathlib.Path)

Returns a pathlib.Path to be able to perform operations accordingly internally.

run_script(→ None)

Runs a script on the filesystem script_path. By default this is a bash script.

write_file(→ bool)

Writes a file to a directory. Appends to the file if it exists and append is True.

write_model_to_json(model, file_path)

Writes a pydantic model to a JSON file.

return_path(→ pathlib.Path)

Returns a pathlib.Path to be able to perform operations accordingly internally.

read_json(→ dict)

Reads a JSON file.

check_path_exists(→ bool)

Checks if a directory exists.

create_new_directory(→ bool)

Creates a new directory.

write_file(→ bool)

Writes a file to a directory. Appends to the file if it exists and append is True.

create_setup_py(→ None)

This function creates a setup.py file from the config.json file found in the design directory.

create_empty_piel_project(→ None)

This function creates an empty piel-structure project in the target directory. Structuring your files in this way

get_module_folder_type_location(module, folder_type)

This is an easy helper function that saves a particular file in the corresponding location of a piel project structure.

pip_install_local_module(module_path)

This function installs a local module in editable mode.

read_configuration(→ dict)

This function reads the configuration file found in the design directory.

round_complex_array(array[, to_absolute])

Rounds the elements of a complex JAX numpy array to the nearest integer.

single_parameter_sweep(base_design_configuration, ...)

This function takes a base_design_configuration dictionary and sweeps a single parameter over a list of values. It returns a list of dictionaries that correspond to the parameter sweep.

multi_parameter_sweep(→ list)

This multiparameter sweep is pretty cool, as it will generate designer list of dictionaries that comprise of all the possible combinations of your parameter sweeps. For example, if you are sweeping parameter_1 = np.arange(0, 2) = array([0, 1]), and parameter_2 = np.arange(2, 4) = array([2, 3]), then this function will generate list of dictionaries based on the default_design dictionary, but that will comprise of all the potential parameter combinations within this list.

get_unique_dataframe_subsets(→ dict[str, pandas.DataFrame])

This function takes a pandas DataFrame and returns a dictionary of unique subsets of the DataFrame.

create_all_connections(→ list[piel.types.ConnectionTypes])

This function receives a list of connection and creates the connections between them as two-port relationships.

create_component_connections(...)

The way this function works is by composing the connection namespaces from the names of the components,

create_sequential_component_path(...)

This function takes in a list of components and creates a sequential path connectivity of components with all the connection defined in each component.

create_connection_list_from_ports_lists(...)

When a list of a list of connection is provided, we construct all the required connections accordingly. TODO more docs.

get_port_index_from_name(→ int)

Extracts the numerical index from a port identifier and adjusts based on starting index.

Package Contents#

check_path_exists(path: piel.types.PathTypes, raise_errors: bool = False) → bool[source]#

Checks if a directory exists.

Parameters:

path (PathTypes) – Input path.

Returns:

True if directory exists.

Return type:

directory_exists(bool)

check_example_design(design_name: str = 'simple_design', designs_directory: piel.types.PathTypes | None = None) → bool[source]#

We copy the example simple_design from docs to the /foss/designs in the iic-osic-tools environment.

Parameters:

  • design_name (str) – Name of the design to check.

  • designs_directory (PathTypes) – Directory that contains the DESIGNS environment flag.

  • TODO (#)

Returns:

None

copy_source_folder(source_directory: piel.types.PathTypes, target_directory: piel.types.PathTypes, delete: bool = None) → None[source]#

Copies the files from a source_directory to a target_directory

Parameters:

  • source_directory (PathTypes) – Source directory.

  • target_directory (PathTypes) – Target directory.

  • delete (bool) – Delete target directory. Default: False.

Returns:

None

copy_example_design(project_source: piel.types.ProjectType = 'piel', example_name: str = 'simple_design', target_directory: piel.types.PathTypes = None, target_project_name: str | None = None, **kwargs) → None[source]#

We copy the example simple_design from docs to the /foss/designs in the iic-osic-tools environment.

Parameters:

  • project_source (str) – Source of the project.

  • example_name (str) – Name of the example design.

  • target_directory (PathTypes) – Target directory.

  • target_project_name (str) – Name of the target project.

Returns:

None

create_new_directory(directory_path: str | pathlib.Path, overwrite: bool = False) → bool[source]#

Creates a new directory.

If the parents of the target_directory do not exist, they will be created too.

Parameters:

  • overwrite – Overwrite directory if it already exists.

  • directory_path (str | pathlib.Path) – Input path.

Returns:

None

create_piel_home_directory() → None[source]#

Creates the piel home directory.

Returns:

None

delete_path(path: str | pathlib.Path) → None[source]#

Deletes a path.

Parameters:

path (str | pathlib.Path) – Input path.

Returns:

None

delete_path_list_in_directory(directory_path: piel.types.PathTypes, path_list: list, ignore_confirmation: bool = False, validate_individual: bool = False) → None[source]#

Deletes a list of files in a directory.

Usage:

```python delete_path_list_in_directory(

directory_path=directory_path, path_list=path_list, ignore_confirmation=True

)#

param directory_path:

Input path.

type directory_path:

PathTypes

param path_list:

List of files.

type path_list:

list

param ignore_confirmation:

Ignore confirmation. Default: False.

type ignore_confirmation:

bool

param validate_individual:

Validate individual files. Default: False.

type validate_individual:

bool

returns:

None

get_files_recursively_in_directory(path: piel.types.PathTypes, extension: str = '*')[source]#

Returns a list of files in a directory.

Usage:

get_files_recursively_in_directory(‘path/to/directory’, ‘extension’)

Parameters:

  • path (PathTypes) – Input path.

  • extension (str) – File extension.

Returns:

List of files.

Return type:

file_list(list)

get_top_level_script_directory() → pathlib.Path[source]#

Attempts to return the top-level script directory when this file is run, compatible with various execution environments like Jupyter Lab, pytest, PDM, etc. TODO run full verification.

Returns:

Top level script directory.

Return type:

top_level_script_directory(pathlib.Path)

get_id_map_directory_dictionary(path_list: list[piel.types.PathTypes], target_prefix: str)[source]#

Returns a dictionary of ids to directories.

Usage:

get_id_to_directory_dictionary(path_list, target_prefix)

Parameters:

  • path_list (list[PathTypes]) – List of paths.

  • target_prefix (str) – Target prefix.

Returns:

Dictionary of ids to directories.

Return type:

id_dict(dict)

list_prefix_match_directories(output_directory: piel.types.PathTypes, target_prefix: str)[source]#

Returns a list of directories that match a prefix.

Usage:

list_prefix_match_directories(‘path/to/directory’, ‘prefix’)

Parameters:

  • output_directory (PathTypes) – Output directory.

  • target_prefix (str) – Target prefix.

Returns:

List of directories.

Return type:

matching_dirs(list)

permit_directory_all(directory_path: piel.types.PathTypes) → None[source]#

Permits a directory to be read, written and executed. Use with care as it can be a source for security issues.

Usage:

permit_directory_all(‘path/to/directory’)

Parameters:

directory_path (PathTypes) – Input path.

Returns:

None

permit_script_execution(script_path: piel.types.PathTypes) → None[source]#

Permits the execution of a script.

Usage:

permit_script_execution(‘path/to/script’)

Parameters:

script_path (PathTypes) – Script path.

Returns:

None

read_json(path: piel.types.PathTypes) → dict[source]#

Reads a JSON file.

Usage:

read_json(‘path/to/file.json’)

Parameters:

path (PathTypes) – Input path.

Returns:

JSON files.

Return type:

json_data(dict)

rename_file(match_file_path: piel.types.PathTypes, renamed_file_path: piel.types.PathTypes) → None[source]#

Renames a file.

Usage:

rename_file(‘path/to/match_file’, ‘path/to/renamed_file’)

Parameters:

  • match_file_path (PathTypes) – Input path.

  • renamed_file_path (PathTypes) – Input path.

Returns:

None

rename_files_in_directory(target_directory: piel.types.PathTypes, match_string: str, renamed_string: str) → None[source]#

Renames all files in a directory.

Usage:

rename_files_in_directory(‘path/to/directory’, ‘match_string’, ‘renamed_string’)

Parameters:

  • target_directory (PathTypes) – Input path.

  • match_string (str) – String to match.

  • renamed_string (str) – String to replace.

Returns:

None

replace_string_in_file(file_path: piel.types.PathTypes, match_string: str, replace_string: str)[source]#

Replaces a string in a file.

Usage:

replace_string_in_file(‘path/to/file’, ‘match_string’, ‘replace_string’)

Parameters:

  • file_path (PathTypes) – Input path.

  • match_string (str) – String to match.

  • replace_string (str) – String to replace.

Returns:

None

replace_string_in_directory_files(target_directory: piel.types.PathTypes, match_string: str, replace_string: str)[source]#

Replaces a string in all files in a directory.

Usage:

replace_string_in_directory_files(‘path/to/directory’, ‘match_string’, ‘replace_string’)

Parameters:

  • target_directory (PathTypes) – Input path.

  • match_string (str) – String to match.

  • replace_string (str) – String to replace.

Returns:

None

return_path(input_path: piel.types.PathTypes, as_piel_module: bool = False) → pathlib.Path[source]#

Returns a pathlib.Path to be able to perform operations accordingly internally.

This allows us to maintain compatibility between POSIX and Windows systems. When the as_piel_module flag is enabled, it will analyse whether the input path can be treated as a piel module, and treat the returned path as a module would be treated. This comes useful when analysing files generated in this particular structure accordingly.

Usage:

return_path(‘path/to/file’)

Parameters:

input_path (str) – Input path.

Returns:

Pathlib path.

Return type:

pathlib.Path

rp#
run_script(script_path: piel.types.PathTypes, program: str = None) → None[source]#

Runs a script on the filesystem script_path. By default this is a bash script.

Parameters:

script_path (PathTypes) – Script path.

Returns:

None

write_file(directory_path: piel.types.PathTypes, file_text: str, file_name: str, append: bool = False) → bool[source]#

Writes a file to a directory. Appends to the file if it exists and append is True.

Parameters:

  • directory_path (PathTypes) – Directory path.

  • file_text (str) – File text.

  • file_name (str) – File name.

  • append (bool) – If True, appends to the file if it exists. Defaults to False.

Returns:

True if successful.

Return type:

bool

write_model_to_json(model: piel.types.PielBaseModel, file_path: piel.types.PathTypes)[source]#

Writes a pydantic model to a JSON file.

PathTypes#
ModuleType#
return_path(input_path: piel.types.PathTypes, as_piel_module: bool = False) → pathlib.Path[source]#

Returns a pathlib.Path to be able to perform operations accordingly internally.

This allows us to maintain compatibility between POSIX and Windows systems. When the as_piel_module flag is enabled, it will analyse whether the input path can be treated as a piel module, and treat the returned path as a module would be treated. This comes useful when analysing files generated in this particular structure accordingly.

Usage:

return_path(‘path/to/file’)

Parameters:

input_path (str) – Input path.

Returns:

Pathlib path.

Return type:

pathlib.Path

read_json(path: piel.types.PathTypes) → dict[source]#

Reads a JSON file.

Usage:

read_json(‘path/to/file.json’)

Parameters:

path (PathTypes) – Input path.

Returns:

JSON files.

Return type:

json_data(dict)

check_path_exists(path: piel.types.PathTypes, raise_errors: bool = False) → bool[source]#

Checks if a directory exists.

Parameters:

path (PathTypes) – Input path.

Returns:

True if directory exists.

Return type:

directory_exists(bool)

create_new_directory(directory_path: str | pathlib.Path, overwrite: bool = False) → bool[source]#

Creates a new directory.

If the parents of the target_directory do not exist, they will be created too.

Parameters:

  • overwrite – Overwrite directory if it already exists.

  • directory_path (str | pathlib.Path) – Input path.

Returns:

None

write_file(directory_path: piel.types.PathTypes, file_text: str, file_name: str, append: bool = False) → bool[source]#

Writes a file to a directory. Appends to the file if it exists and append is True.

Parameters:

  • directory_path (PathTypes) – Directory path.

  • file_text (str) – File text.

  • file_name (str) – File name.

  • append (bool) – If True, appends to the file if it exists. Defaults to False.

Returns:

True if successful.

Return type:

bool

create_setup_py(design_directory: piel.types.PathTypes, project_name: str | None = None, from_config_json: bool = True) → None[source]#

This function creates a setup.py file from the config.json file found in the design directory.

Parameters:

design_directory (PathTypes) – Design directory PATH or module name.

Returns:

None

create_empty_piel_project(project_name: str, parent_directory: piel.types.PathTypes) → None[source]#

This function creates an empty piel-structure project in the target directory. Structuring your files in this way enables the co-design and use of the tools supported by piel whilst maintaining the design flow ordered, clean and extensible. You can read more about it in the documentation TODO add link.

TODO just make this a cookiecutter. TO BE DEPRECATED whenever I get round to that.

Parameters:

  • project_name (str) – Name of the project.

  • parent_directory (PathTypes) – Parent directory of the project.

Returns:

None

get_module_folder_type_location(module: piel.types.ModuleType, folder_type: Literal['digital_source', 'digital_testbench'])[source]#

This is an easy helper function that saves a particular file in the corresponding location of a piel project structure.

TODO DOCS

pip_install_local_module(module_path: piel.types.PathTypes)[source]#

This function installs a local module in editable mode.

Parameters:

module_path (PathTypes) – Path to the module to be installed.

Returns:

None

read_configuration(design_directory: piel.types.PathTypes) → dict[source]#

This function reads the configuration file found in the design directory.

Parameters:

design_directory (PathTypes) – Design directory PATH.

Returns:

Configuration dictionary.

Return type:

config_dictionary(dict)

round_complex_array(array: piel.types.ArrayTypes, to_absolute: bool = False)[source]#

Rounds the elements of a complex JAX numpy array to the nearest integer.

Parameters: - array: A complex JAX numpy array. - absolute: A boolean that determines whether the complex numbers are rounded to the nearest integers in their absolute value.

Returns: - A JAX numpy array with the complex elements rounded to the nearest integers.

single_parameter_sweep(base_design_configuration: dict, parameter_name: str, parameter_sweep_values: list)[source]#

This function takes a base_design_configuration dictionary and sweeps a single parameter over a list of values. It returns a list of dictionaries that correspond to the parameter sweep.

Parameters:

  • base_design_configuration (dict) – Base design configuration dictionary.

  • parameter_name (str) – Name of parameter to sweep.

  • parameter_sweep_values (list) – List of values to sweep.

Returns:

List of dictionaries that correspond to the parameter sweep.

Return type:

parameter_sweep_design_dictionary_array(list)

multi_parameter_sweep(base_design_configuration: dict, parameter_sweep_dictionary: dict) → list[source]#

This multiparameter sweep is pretty cool, as it will generate designer list of dictionaries that comprise of all the possible combinations of your parameter sweeps. For example, if you are sweeping parameter_1 = np.arange(0, 2) = array([0, 1]), and parameter_2 = np.arange(2, 4) = array([2, 3]), then this function will generate list of dictionaries based on the default_design dictionary, but that will comprise of all the potential parameter combinations within this list.

For the example above, there arould be 4 combinations [(0, 2), (0, 3), (1, 2), (1, 3)].

If you were instead sweeping for parameter_1 = np.arange(0, 5) and parameter_2 = np.arange(0, 5), the dictionary generated would correspond to these parameter combinations of::

[(0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (1, 0), (1, 1), (1, 2), (1, 3), (1, 4), (2, 0), (2, 1), (2, 2), (2, 3), (2, 4), (3, 0), (3, 1), (3, 2), (3, 3), (3, 4), (4, 0), (4, 1), (4, 2), (4, 3), (4, 4)].

Make sure to use the parameter_names from default_design when writing up the parameter_sweep dictionary key name.

Example project_structure formats:

example_parameter_sweep_dictionary = {
    "parameter_1": np.arange(1, -40, 1),
    "parameter_2": np.arange(1, -40, 1),
}

example_base_design_configuration = {
    "parameter_1": 10.0,
    "parameter_2": 40.0,
    "parameter_3": 0,
}
Parameters:

  • base_design_configuration (dict) – Dictionary of the default design configuration.

  • parameter_sweep_dictionary (dict) – Dictionary of the parameter sweep. The keys should be the same as the keys in the base_design_configuration dictionary.

Returns:

List of dictionaries that comprise of all the possible combinations of your parameter sweeps.

Return type:

parameter_sweep_design_dictionary_array(list)

get_unique_dataframe_subsets(dataframe: pandas.DataFrame, max_depth: int = 2) → dict[str, pandas.DataFrame][source]#

This function takes a pandas DataFrame and returns a dictionary of unique subsets of the DataFrame. It is useful for identifying unique operating points in a dataset. The function returns a dictionary where the keys are string identifiers for the subsets, and the values are DataFrames containing the unique combinations of values for each column in the input DataFrame.

Parameters:

  • dataframe (pd.DataFrame)

  • max_depth (int, optional) – The maximum depth of combinations to consider. For example, if max_depth is 2, only combinations of up to 2 columns will be generated.

Returns:

A dictionary where the keys are string identifiers for the subsets and the values are DataFrames containing the unique combinations of values.

Return type:

dict[str, pd.DataFrame]

create_all_connections(ports: list[piel.types.Port], connection_factory: Callable[[list[piel.types.Port]], piel.types.Connection] | None = None, connection_type_output: piel.types.ConnectionTypes | None = Connection) → list[piel.types.ConnectionTypes][source]#

This function receives a list of connection and creates the connections between them as two-port relationships. It returns a list of connections. More than two connection can be provided, and it will create all the possible connections.

Parameters:

  • ports (list[Port]) – The connection list to create connections.

  • connection_factory (Optional[Callable[[list[Port]], Connection]], optional) – A function that creates a connection object from a list of connection. The function should receive a list of connection and return a connection object. If not provided, a default connection factory will be used. The default connection factory creates a tuple of connection as a connection object. The default is None.

  • connection_type_output (Optional[type[Connection]], optional) –

    The type of connection object to return.

    If not provided, the default connection factory will be used.

    The default is None

Returns:

A list of connections that were created.

Return type:

list[Connection]

create_component_connections(components: list[piel.types.ComponentTypes], connection_reference_str_list: list[str] | list[list[str]]) → list[piel.types.ConnectionTypes][source]#

The way this function works is by composing the connection namespaces from the names of the components, and a given connection dot notation which corresponds to that component.

Notes

The dot notation would be in the format "component_1.port1". Hence, the input to a connection would be ["component1.port1", "component2.port1"] and this function would compile into generating the corresponding connection. This is by splitting the component name and port name accordingly and then programmatically acquiring the corresponding Port reference and creating the Connection from this.

Parameters:

  • components (list[ComponentTypes]) – The components to create connections from.

  • connection_reference_str_list (list[str] | list[list[str]]) – The list of strings that represent the connections to create.

Returns:

The list of connections created from the components.

Return type:

list[ConnectionTypes]

create_sequential_component_path(components: list[piel.types.ComponentTypes], name: str = '', **kwargs) → piel.types.ComponentTypes[source]#

This function takes in a list of components and creates a sequential path connectivity of components with all the connection defined in each component. By default, the connectivity will be implemented with the first two connection of the components. There is a clear input and output on each component. The timing metric calculations is provided by the timing model of each connection of the component, if there is none defined it will assume a default zero time connectivity between the relevant connection. For the output component collection, it will output the timing of the network as a whole based on the defined subcomponents. This will create an output component with all the subcomponents, TODO more than two connection, and the list of connection

Creates a sequential path connectivity of components with all the connection defined in each component.

Parameters:#

componentsList[ComponentTypes]

A list of components to be connected sequentially.

Returns:#

: ComponentTypes

A new component that encapsulates the sequential path of input components.

create_connection_list_from_ports_lists(port_connection_list: list[list[piel.types.Port]]) → list[piel.types.ConnectionTypes][source]#

When a list of a list of connection is provided, we construct all the required connections accordingly. TODO more docs.

get_port_index_from_name(port: piel.types.Port, starting_index: int | None = None) → int[source]#

Extracts the numerical index from a port identifier and adjusts based on starting index. If port numbering starts at 0, adds 1. If starts at 1 or is None, leaves as is.

Parameters: - port (int or str): The port identifier. - starting_index (int, optional): The starting index (0 or 1). Defaults to None.

Returns: - int: The adjusted numerical index of the port.

Raises: - ValueError: If starting_index is not 0, 1, or None. - ValueError: If the port string does not contain a numerical index. - TypeError: If the port is neither int nor str.

__author__ = 'Dario Quintero'#
__email__ = 'darioaquintero@gmail.com'#
__version__ = '0.1.0'#
Contents