piel.flows#

Submodules#

Functions#

`extract_component_spice_from_netlist`(component[, ...])
`generate_verilog_and_verification_from_truth_table`(...)	Processes a truth table to generate an Amaranth module, converts it to Verilog,
`get_latest_digital_run_component`(...)
`read_simulation_data_to_truth_table`(...)	The goal of this function is to read an existing simulation files output from cocotb and convert it into a valid Dataframe with proper type validation of bit signals into the corresponding byte formats.
`run_verification_simulation_for_design`(module, ...[, ...])	Configures and runs a Cocotb simulation for a given design module and retrieves the simulation files.
`layout_truth_table`(→ piel.types.ElectronicCircuitComponent)	Layout a truth table through the OpenLane flow and create a GDSFactory component.
`add_truth_table_phase_to_bit_data`(→ piel.types.TruthTable)	This function converts the phase column of a dataframe into a bit tuple using the phase_bit_dataframe. The
`convert_phase_to_bit_iterable`(→ tuple)	This function converts a phase array or tuple iterable, into the corresponding mapping of their bitstring
`find_nearest_bit_for_phase`(→ tuple)	This is a mapping function between a provided target phase that might be more analogous, with the closest
`find_nearest_phase_for_bit`(→ piel.types.PhaseMapType)	Maps a bitstring to the nearest phase(s) in a phase-bit mapping dataframe.
`extract_phase_from_fock_state_transitions`(...[, ...])	Extracts the phase corresponding to the specified transition type.
`format_electro_optic_fock_transition`(...)	Formats the electro-optic state into a standard FockStatePhaseTransition format. This is useful for the
`generate_s_parameter_circuit_from_photonic_circuit`(...)	Generates the S-parameters and related information for a given circuit using SAX and custom measurement.
`get_state_phase_transitions`(...)	The goal of this function is to extract the corresponding phase required to implement a state transition.
`get_state_to_phase_map`(→ tuple[piel.types.ArrayTypes])	The goal of this function is to extract the corresponding phase required to implement a state transition.

Package Contents#

extract_component_spice_from_netlist(component: piel.types.CircuitComponent, output_path: piel.types.PathTypes = sys.stdout, fmt: str = 'spice')[source]#

generate_verilog_and_verification_from_truth_table(module: piel.types.PathTypes, truth_table: piel.types.TruthTable, target_file_name: str = 'truth_table_module')[source]#

Processes a truth table to generate an Amaranth module, converts it to Verilog, and creates a testbench for verification.

Parameters: - truth_table (dict): The truth table defining the logic. It should be a dictionary where keys are

port names and values are lists of binary strings representing the truth table entries. Example: {“detector_in”: [“00”, “01”, “10”, “11”], “phase_map_out”: [“00”, “10”, “11”, “11”]}

input_ports (list of str): A list of input port names that correspond to keys in the truth table.
Example: [“detector_in”]
output_ports (list of str): A list of output port names that correspond to keys in the truth table.
Example: [“phase_map_out”]
module (str): The name or path of the module within the design hierarchy where the generated files
will be placed. This is used to determine the file structure and directory paths. Example: “full_flow_demo”
target_file_name (str): The verilog and vcd file name.

Returns: - None

Steps: 1. Combines the input and output connection into a single list. 2. Constructs an Amaranth module from the provided truth table. 3. Determines the appropriate directory and source folder for the design. 4. Generates a Verilog file from the Amaranth module. 5. Creates a testbench to verify the generated module logic and produces a VCD file.

get_latest_digital_run_component(module: piel.types.PathTypes, *args, **kwargs) → piel.types.CircuitComponent[source]#

read_simulation_data_to_truth_table(file_path: piel.types.PathTypes, input_ports: piel.types.LogicSignalsList, output_ports: piel.types.LogicSignalsList, *args, **kwargs) → piel.types.TruthTable[source]#

The goal of this function is to read an existing simulation files output from cocotb and convert it into a valid Dataframe with proper type validation of bit signals into the corresponding byte formats.

Args: - file_path (PathTypes): The path to the simulation files file. - input_ports (LogicSignalsList): The list of input port names. - output_ports (LogicSignalsList): The list of output port names.

Returns: - truth_table (TruthTable): The truth table object containing the input and output port files.

Examples: >>> read_simulation_data_to_truth_table(“simulation_data.csv”, [“input_port”], [“output_port”]) TruthTable(input_ports=[“input_port”], output_ports=[“output_port”], …)

run_verification_simulation_for_design(module: piel.types.PathTypes, top_level_verilog_module: str, test_python_module: str, simulator: piel.types.HDLSimulator = 'icarus')[source]#

Configures and runs a Cocotb simulation for a given design module and retrieves the simulation files. TODO possibly in the future swap the methodology of running the simulation here.

Parameters: - module (str): The name or path of the module within the design hierarchy where the generated files

will be placed. This is used to determine the file structure and directory paths. Example: “full_flow_demo”

top_level_verilog_module (str): The name of the top-level Verilog module in the design.
Example: “full_flow_demo_module”
test_python_module (str): The name of the Python test module for the design.
Example: “test_full_flow_demo”
simulator (HDLSimulator): The simulator to use for the Cocotb simulation. Default is “icarus”.

Returns: - example_simulation_data: The simulation files read from the output files.

layout_truth_table(truth_table: piel.types.TruthTable, module: piel.types.PathTypes) → piel.types.ElectronicCircuitComponent[source]#

Layout a truth table through the OpenLane flow and create a GDSFactory component.

Parameters: - truth_table (TruthTable): The truth table object containing the input and output port files. - module (str): The name or path of the module within the design hierarchy where the generated files

will be placed. This is used to determine the file structure and directory paths. Example: “full_flow_demo”

Returns: - digital_component (gf.Component): The GDSFactory component representing the layout of the truth table as implemented by OpenLane

add_truth_table_phase_to_bit_data(truth_table: piel.types.TruthTable, bit_phase_map: piel.types.BitPhaseMap, phase_column_name: str = None, rounding_function: Callable | None = None) → piel.types.TruthTable[source]#

This function converts the phase column of a dataframe into a bit tuple using the phase_bit_dataframe. The phase_bit_dataframe is a dataframe that maps the phase to the bit. The phase_series_name is the name of the phase series in the phase_bit_dataframe. The bit_series_name is the name of the bit series in the phase_bit_dataframe. The phase_column_name is the name of the phase column in the dataframe. The function returns a tuple of bits that correspond to the phase column of the dataframe.

Parameters:

truth_table (pd.DataFrame) – The dataframe that contains the phase column.
bit_phase_map (BitPhaseMap) – The dataframe that maps the phase to the bit.
rounding_function (Optional[Callable]) – The rounding function that is used to round the phase to the nearest phase in the phase_bit_dataframe.

Returns:

A tuple of bits that correspond to the phase column of the dataframe.

Return type:

tuple

convert_phase_to_bit_iterable(phase: piel.types.PhaseMapType, bit_phase_map: piel.types.BitPhaseMap, rounding_function: Callable | None = None) → tuple[source]#

This function converts a phase array or tuple iterable, into the corresponding mapping of their bitstring required within a particular bit-phase mapping. A phase_array iterable is provided, and each phase is mapped to a particular bitstring based on the phase_bit_dataframe. A tuple is composed of strings that represent the bitstrings of the phases provided.

Parameters:

phase (Iterable) – Iterable of phases to map to bitstrings.
bit_phase_map (BitPhaseMap) – Dataframe containing the phase-bits mapping.
rounding_function (Callable) – Rounding function to apply to the target phase.

Returns:

Tuple of bitstrings corresponding to the phases.

Return type:

bit_array(tuple)

find_nearest_bit_for_phase(target_phase: float, bit_phase_map: piel.types.BitPhaseMap, rounding_function: Callable | None = None) → tuple[source]#

This is a mapping function between a provided target phase that might be more analogous, with the closest bit-value in a bit-phase ideal relationship. The error between the target phase and the applied phase is limited to the discretisation error of the phase mapping.

Parameters:

target_phase (float) – Target phase to map to.
bit_phase_map (pd.DataFrame) – Dataframe containing the phase-bits mapping.
rounding_function (Callable) – Rounding function to apply to the target phase.

Returns:

Bitstring corresponding to the nearest phase.

Return type:

bitstring(str)

find_nearest_phase_for_bit(bits: piel.types.BitsType, phase_map: piel.types.BitPhaseMap) → piel.types.PhaseMapType[source]#

Maps a bitstring to the nearest phase(s) in a phase-bit mapping dataframe.

Parameters:

bits (AbstractBitsType) – Bitstring to map to a phase.
phase_map (BitPhaseMap) – Dataframe containing the phase-bits mapping.

Returns:

Tuple of phases or an empty tuple if no match is found.

Return type:

Tuple[str, …]

extract_phase_from_fock_state_transitions(optical_state_transitions: piel.types.OpticalStateTransitionCollection, transition_type: piel.types.PhaseTransitionTypes = 'cross')[source]#

Extracts the phase corresponding to the specified transition type.

Parameters: optical_state_transitions (OpticalStateTransitionCollection): Optical state transitions.

transition_type (str): Type of transition to extract phase for (‘cross’ or ‘bar’).

Returns:: Phase corresponding to the specified transition type.
Return type:: float

format_electro_optic_fock_transition(switch_state_array: piel.types.ArrayTypes, input_fock_state_array: piel.types.ArrayTypes, raw_output_state: piel.types.ArrayTypes, **kwargs) → piel.types.FockStatePhaseTransition[source]#

Formats the electro-optic state into a standard FockStatePhaseTransition format. This is useful for the electro-optic model to ensure that the output state is in the correct format. The output state is a dictionary that contains the phase, input fock state, and output fock state. The idea is that this will allow us to standardise and compare the output states of the electro-optic model across multiple formats.

Parameters:

switch_state_array (array_types) – Array of switch states.
input_fock_state_array (array_types) – Array of valid input fock states.
raw_output_state (array_types) – Array of raw output state.
**kwargs – Additional keyword arguments.

Returns:

Electro-optic state.

Return type:

electro_optic_state(FockStatePhaseTransition)

generate_s_parameter_circuit_from_photonic_circuit(circuit: piel.types.PhotonicCircuitComponent, models: Any = None, netlist_function: Callable | None = None) → tuple[any, any][source]#

Generates the S-parameters and related information for a given circuit using SAX and custom measurement.

Parameters:

circuit (gf.Component) – The circuit for which the S-parameters are to be generated.
models (sax.ModelFactory, optional) – The measurement to be used for the S-parameter generation. Defaults to None.
netlist_function (Callable, optional) – The function to generate the netlist. Defaults to None.

Returns:

The S-parameters circuit and related information.

Return type:

tuple[any, any]

get_state_phase_transitions(circuit_component: piel.types.PhotonicCircuitComponent, models: dict = None, mode_amount: int = None, input_fock_states: list[piel.types.ArrayTypes] | None = None, switch_states: list[piel.types.NumericalTypes] | None = None, determine_ideal_mode_function: Callable | None = None, netlist_function: Callable | None = None, target_mode_index: int | None = None, **kwargs) → piel.types.OpticalStateTransitionCollection[source]#

The goal of this function is to extract the corresponding phase required to implement a state transition.

Let’s consider a simple MZI 2x2 logic with two transmission states. We want to verify that the electronic function switch, effectively switches the optical output between the cross and bar states of the optical transmission function.

For the corresponding switch model:

Let’s assume a switch model unitary. For a given 2x2 input optical switch “X”. In bar state, in dual rail, transforms an optical input: ``` .. raw:

[[1] ----> [[1]
[0]]        [0]]

In cross state, in dual rail, transforms an optical input:

However, sometimes it is easier to describe a photonic logic transformation based on these states, rather than inherently the numerical phase that is applied. This may be the case, for example, in asymmetric Mach-Zehnder modulators measurement, etc.

As such, this function will help us extract the corresponding phase for a particular switch transition.

When the switch function is larger than a single switch, it is necessary to extract the location of the corresponding switches as function parameters.

get_state_to_phase_map(switch_function: piel.types.OpticalTransmissionCircuit, switch_states: list[piel.types.NumericalTypes] | None = None, input_fock_states: list[piel.types.ArrayTypes] | None = None, target_transition_list: list[dict] | None = None, mode_amount: int | None = None, **kwargs) → tuple[piel.types.ArrayTypes][source]#

The goal of this function is to extract the corresponding phase required to implement a state transition.

For the corresponding switch model:

Let’s assume a switch model unitary. For a given 2x2 input optical switch “X”. In bar state, in dual rail, transforms an optical input: ``` .. raw:

[[1] ----> [[1]
[0]]        [0]]

In cross state, in dual rail, transforms an optical input:

As such, this function will help us extract the corresponding phase for a particular switch transition.