1 Welcome to the Pareto DAB (Dual Active Bridge) Tool

1.1 Installation

Install the Toolbox as a developer

pip install -e .

2 DAB Computational Toolbox (DCT) documentation

Init python files as modules.

class dct.Any(*args, **kwargs)

Bases: object

Special type indicating an unconstrained type.

• Any is compatible with every type.

• Any assumed to have all methods.

• All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class dct.BoundaryCheck

Bases: object

Boundary check for parameter.

static check_dictionary(keyword_dictionary: dict, keyword: str, keyword_list_name: str) → tuple[bool, str]

Check the keyword according match in keyword dictionary.

Parameters:

• keyword_dictionary (dict) – Dictionary with keywords

• keyword (str) – Keyword to check

• keyword_list_name (str) – Name of keyword to mention in inconsistency report, if check fails

Returns:

tuple: Indication if the verification failed | Error text with description about the deviation

Return type:

tuple[bool, str]

static check_float_min_max_values(minimum: float, maximum: float, min_max_value: list[float], parameter_name: str, check_type_minimum: CheckCondition, check_type_maximum: CheckCondition) → tuple[bool, str]

Perform a boundary check for the minimum/maximum-pair.

Parameters:

• minimum (float) – Minimum value of the range

• maximum (float) – Maximum value of the range

• min_max_value (list[tuple[list[float], str]]) – 2 float values for the minimum and maximum boundary check

• parameter_name (str) – Name of parameter to mention in inconsistency report, if check fails

• check_type_minimum (CheckCondition) – Type of check to perform according the minimum value

• check_type_maximum (CheckCondition) – Type of check to perform according the maximum value

Returns:

tuple: Indication if the verification failed | Error text with description about the deviation

Return type:

tuple[bool, str]

static check_float_min_max_values_list(minimum: float, maximum: float, min_max_value_list: list[tuple[list[float], str]], check_type_minimum: CheckCondition, check_type_maximum: CheckCondition) → tuple[bool, str]

Perform a boundary check of the minimum/maximum-pair.

Parameters:

• minimum (float) – Minimum value of the range

• maximum (float) – Maximum value of the range

• min_max_value_list (list[tuple[list[float], str]]) – List of 2 float values according provided minimum and maximum to check and the parameter name

• check_type_minimum (CheckCondition) – Type of check to perform according the minimum value

• check_type_maximum (CheckCondition) – Type of check to perform according the maximum value

Returns:

tuple: Indication if the verification failed | Error text with description about the deviation

Return type:

tuple[bool, str]

static check_float_value(minimum: float, maximum: float, parameter_value: float, parameter_name: str, check_type_minimum: CheckCondition, check_type_maximum: CheckCondition) → tuple[bool, str]

Verify the value according minimum and maximum.

Parameters:

• minimum (float) – Minimum value of the range

• maximum (float) – Maximum value of the range

• parameter_value (float) – Float values to check and the value name

• parameter_name (str) – Name of parameter to mention in inconsistency report, if check fails

• check_type_minimum (CheckCondition) – Type of check to perform according the minimum value

• check_type_maximum (CheckCondition) – Type of check to perform according the maximum value

Returns:

tuple: Indication if the verification failed | Error text with description about the deviation

Return type:

tuple[bool, str]

static check_float_value_list(minimum: float, maximum: float, value_list: list[tuple[float, str]], check_type_minimum: CheckCondition, check_type_maximum: CheckCondition) → tuple[bool, str]

Verify the listed values according minimum and maximum.

Parameters:

• minimum (float) – Minimum value of the range

• maximum (float) – Maximum value of the range

• value_list (list[tuple[float, str]]) – List of float values to check and the parameter name

• check_type_minimum (CheckCondition) – Type of check to perform according the minimum value

• check_type_maximum (CheckCondition) – Type of check to perform according the maximum value

Returns:

tuple: Indication if the verification failed | Error text with description about the deviation

Return type:

tuple[bool, str]

static convert_min_max_values_to_float(int_value_list: list[int]) → list[float]

Convert a list of integer values in a list of float values.

Parameters:

int_value_list (list[int]) – List of integer values

Returns:

List of float values

Return type:

list[float]

class dct.Breakpoints(*, circuit_pareto: Literal['no', 'pause', 'stop'], circuit_filtered: Literal['no', 'pause', 'stop'], inductor: Literal['no', 'pause', 'stop'], transformer: Literal['no', 'pause', 'stop'], heat_sink: Literal['no', 'pause', 'stop'], pre_summary: Literal['no', 'pause', 'stop'], summary: Literal['no', 'pause', 'stop'])

Bases: BaseModel

Flow control breakpoints.

circuit_filtered: Literal['no', 'pause', 'stop']

circuit_pareto: Literal['no', 'pause', 'stop']

heat_sink: Literal['no', 'pause', 'stop']

inductor: Literal['no', 'pause', 'stop']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pre_summary: Literal['no', 'pause', 'stop']

summary: Literal['no', 'pause', 'stop']

transformer: Literal['no', 'pause', 'stop']

class dct.CalcCurrents(**kwargs)

Bases: object

DTO contains calculated RMS currents.

angles_rad_sorted: ndarray

angles_rad_unsorted: ndarray

i_hf_1_rms: ndarray

i_hf_1_sorted: ndarray

i_hf_2_rms: ndarray

i_hf_2_sorted: ndarray

i_l_1_rms: ndarray

i_l_1_sorted: ndarray

i_l_2_rms: ndarray

i_l_2_sorted: ndarray

i_l_s_rms: ndarray

i_l_s_sorted: ndarray

i_m1_rms: ndarray

i_m2_rms: ndarray

class dct.CalcFromCircuitConfig(**kwargs)

Bases: object

DTO calculates parameters for the next simulations, which can be derived from the input values.

Lc2_: ndarray

c_oss_1: ndarray

c_oss_2: ndarray

c_oss_par_1: ndarray

c_oss_par_2: ndarray

q_oss_1: ndarray

q_oss_2: ndarray

t_j_1: float64

t_j_2: float64

class dct.CalcLosses(**kwargs)

Bases: object

DTO contains the calculated losses.

p_dab_conduction: ndarray

p_m1_conduction: ndarray

p_m2_conduction: ndarray

class dct.CalcModulation(**kwargs)

Bases: object

DTO contains calculated modulation parameters.

mask_IIIm1: ndarray

mask_IIm2: ndarray

mask_Im2: ndarray

mask_m1n: ndarray

mask_m1p: ndarray

mask_zvs: ndarray

mask_zvs_coverage: ndarray

mask_zvs_coverage_notnan: ndarray

phi: ndarray

tau1: ndarray

tau2: ndarray

class dct.CheckCondition(*values)

Bases: Enum

Enum for type of check.

check_exclusive = 2

check_ignore = 0

check_inclusive = 1

class dct.Circuit(*, number_of_trials: int, calculation_mode: Literal['new', 'continue', 'skip'], subdirectory: str)

Bases: BaseModel

Flow control for the circuit.

calculation_mode: Literal['new', 'continue', 'skip']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_of_trials: int

subdirectory: str

class dct.CircuitConfig(**kwargs)

Bases: object

Input configuration DTO for the DAB converter.

Lc1: float64

Lc2: float64

Ls: float64

c_par_1: float64

c_par_2: float64

fs: float64

mesh_p: ndarray

mesh_v1: ndarray

mesh_v2: ndarray

n: float64

sampling: Sampling

transistor_dto_1: TransistorDTO

transistor_dto_2: TransistorDTO

class dct.CircuitConfigurationDataDto(configuration_name: str, number_of_trials: int, filtered_points_name_list: list[tuple[str, int] | Any], progress_data: ProgressData)

Bases: object

DTO for queue circuit configuration information transfer.

configuration_name: str

filtered_points_name_list: list[tuple[str, int] | Any]

number_of_trials: int

progress_data: ProgressData

class dct.CircuitDabDTO(timestamp: ndarray | None, name: str, metadata: ndarray | None, input_config: CircuitConfig, calc_config: CalcFromCircuitConfig, calc_modulation: CalcModulation, calc_currents: CalcCurrents, calc_losses: CalcLosses | None, gecko_additional_params: GeckoAdditionalParameters, gecko_results: GeckoResults | None, gecko_waveforms: GeckoWaveforms | None, inductor_results: InductorResults | None, stacked_transformer_results: StackedTransformerResults | None)

Bases: object

Main DabDTO containing all input parameters, calculations and simulation results.

calc_config: CalcFromCircuitConfig

calc_currents: CalcCurrents

calc_losses: CalcLosses | None

calc_modulation: CalcModulation

gecko_additional_params: GeckoAdditionalParameters

gecko_results: GeckoResults | None

gecko_waveforms: GeckoWaveforms | None

inductor_results: InductorResults | None

input_config: CircuitConfig

metadata: ndarray | None

name: str

stacked_transformer_results: StackedTransformerResults | None

timestamp: ndarray | None

class dct.CircuitFilter(number_filtered_designs: int, difference_percentage: float)

Bases: object

Filter the results.

difference_percentage: float

number_filtered_designs: int

class dct.CircuitOptimization

Bases: object

Optimize the DAB converter regarding maximum ZVS coverage and minimum conduction losses.

static calculate_fixed_parameters(act_dab_config: CircuitParetoDabDesign) → FixedParameters

Calculate time-consuming parameters which are same for every single simulation.

Parameters:

act_dab_config (circuit_dtos.CircuitParetoDabDesign) – DAB circuit configuration

Returns:

Fix parameters (transistor DTOs)

Return type:

d_dtos.FixedParameters

static create_sqlite_database_url(dab_config: CircuitParetoDabDesign) → str

Create the DAB circuit optimization sqlite URL.

Parameters:

dab_config (circuit_dtos.CircuitParetoDabDesign) – DAB optimization configuration file

Returns:

SQLite URL

Return type:

str

static df_plot_pareto_front(df: DataFrame, figure_size: tuple) → None

Plot an interactive Pareto diagram (losses vs. volume) to select the transformers to re-simulate.

Parameters:

• df (pd.DataFrame) – DataFrame, generated from an optuna study (exported by optuna)

• figure_size (tuple) – figure size as x,y-tuple in mm, e.g. (160, 80)

df_to_dab_dto_list(df: DataFrame) → list[CircuitDabDTO]

Load a DAB-DTO from an optuna study.

Parameters:

df (pd.DataFrame) – Pandas DataFrame to convert to the DAB-DTO list

Returns:

List of DTO

Return type:

list[d_dtos.CircuitDabDTO]

static filter_df(df: DataFrame, x: str = 'values_0', y: str = 'values_1', factor_min_dc_losses: float = 1.2, factor_max_dc_losses: float = 10) → DataFrame

Remove designs with too high losses compared to the minimum losses.

Parameters:

• df (pd.DataFrame) – pandas DataFrame with study results

• x (str) – x-value name for Pareto plot filtering

• y (str) – y-value name for Pareto plot filtering

• factor_min_dc_losses (float) – filter factor for the minimum dc losses

• factor_max_dc_losses (float) – dc_max_loss = factor_max_dc_losses * min_available_dc_losses_in_pareto_front

Returns:

pandas DataFrame with Pareto front near points

Return type:

pd.DataFrame

filter_study_results() → None

Filter the study result and use GeckoCIRCUITS for detailed calculation.

get_actual_pareto_html() → str

Read the current Pareto front from running optimization process.

Returns:

Pareto front html page

Return type:

str

get_config() → CircuitParetoDabDesign | None

Return the actual loaded configuration file.

Returns:

Configuration file as circuit_dtos.DabDesign

Return type:

circuit_dtos.CircuitParetoDabDesign

static get_pareto_html(study_name: str, path_name: str) → str

Read the current Pareto front from running optimization process.

Parameters:

• study_name (str) – Name of the optuna study

• path_name (str) – Path where optuna study is located

Returns:

Pareto front html page

Return type:

str

get_progress_data() → ProgressData

Provide the progress data of the optimization.

Returns:

Progress data: Processing start time, actual processing time, number of filtered operation points and status.

Return type:

ProgressData

initialize_circuit_optimization(toml_circuit: TomlCircuitParetoDabDesign, toml_prog_flow: FlowControl) → bool

Initialize the circuit_dto for circuit optimization.

Parameters:

• toml_circuit (tc.TomlCircuitParetoDabDesign) – toml file class for the circuit

• toml_prog_flow (tc.FlowControl) – toml file class for the flow control

Returns:

True, if the configuration was successful initialized

Return type:

bool

static is_pareto_efficient(costs: ndarray, return_mask: bool = True) → ndarray

Find the pareto-efficient points.

Parameters:

• costs (np.array) – An (n_points, n_costs) array

• return_mask (bool) – True to return a mask

Returns:

An array of indices of pareto-efficient points. If return_mask is True, this will be an (n_points, ) boolean array Otherwise it will be a (n_efficient_points, ) integer array of indices.

Return type:

np.array

static load_csv_to_df(csv_filepath: str) → DataFrame

Load a csv file (previously stored from a Pandas DataFrame) back to a Pandas DataFrame.

Parameters:

csv_filepath (str) – File path of .csv file

Returns:

loaded results from the given .csv file

Return type:

pandas.DataFrame

static load_dab_dto_from_study(dab_config: CircuitParetoDabDesign, trial_number: int | None = None) → CircuitDabDTO

Load a DAB-DTO from an optuna study.

Parameters:

• dab_config (circuit_dtos.CircuitParetoDabDesign) – DAB optimization configuration file

• trial_number (int) – trial number to load to the DTO

Returns:

static load_filepaths(project_directory: str) → ParetoFilePaths

Load file path of the subdirectories of the project.

Parameters:

project_directory (str) – project directory file path

Returns:

File path in a DTO

Return type:

circuit_dtos.ParetoFilePaths

static load_stored_config(circuit_project_directory: str, circuit_study_name: str) → CircuitParetoDabDesign

Load pickle configuration file from disk.

Parameters:

• circuit_project_directory (str) – project directory

• circuit_study_name (str) – name of the circuit study

Returns:

Configuration file as circuit_dtos.DabDesign

Return type:

circuit_dtos.CircuitParetoDabDesign

static pareto_front_from_df(df: DataFrame, x: str = 'values_0', y: str = 'values_1') → DataFrame

Calculate the Pareto front from a Pandas DataFrame. Return a Pandas DataFrame.

Parameters:

• df (pd.DataFrame) – Pandas DataFrame

• x (str) – Name of x-parameter from df to show in Pareto plane

• y (str) – Name of y-parameter from df to show in Pareto plane

Returns:

Pandas DataFrame with pareto efficient points

Return type:

pd.DataFrame

run_optimization_mysql(act_storage_url: str, act_number_trials: int) → None

Proceed a study which is stored as sqlite database.

Parameters:

• act_storage_url (str) – url-Name of the database path

• act_number_trials (int) – Number of trials adding to the existing study

run_optimization_sqlite(act_number_trials: int) → None

Proceed a study which is stored as sqlite database.

Parameters:

act_number_trials (int) – Number of optimization trials

save_config() → None

Save the actual configuration file as pickle file on the disk.

save_study_results_pareto(show_results: bool = False) → None

Show the results of a study.

A local .html file is generated under config.working_directory to store the interactive plotly plots on disk.

Parameters:

show_results (bool) – True to directly open the browser to show the study results.

start_proceed_study(number_trials: int, database_type: str = 'sqlite', sampler: ~optuna.samplers._base.BaseSampler = <optuna.samplers._nsgaiii._sampler.NSGAIIISampler object>) → None

Proceed a study which is stored as sqlite database.

Parameters:

• number_trials (int) – Number of trials adding to the existing study

• database_type (str) – storage database, e.g. ‘sqlite’ or ‘mysql’

• sampler (optuna.sampler-object) – optuna.samplers.NSGAIISampler() or optuna.samplers.NSGAIIISampler(). Note about the brackets () !! Default: NSGAIII

static study_to_df(dab_config: CircuitParetoDabDesign) → DataFrame

Create a DataFrame from a study.

Parameters:

dab_config (circuit_dtos.CircuitParetoDabDesign) – DAB optimization configuration file

static verify_optimization_parameter(toml_circuit: TomlCircuitParetoDabDesign, is_tdb_to_update: bool = False) → tuple[bool, str]

Verify the input parameter ranges.

Parameters:

• toml_circuit (dct.TomlInductor) – toml inductor configuration

• is_tdb_to_update (bool) – True to update the transistor database

Returns:

True, if the configuration was consistent

Return type:

bool

class dct.CircuitOutputRange(v1_min_max_list: list, v2_min_max_list: list, p_min_max_list: list)

Bases: object

Definition of the DAB operating area.

p_min_max_list: list

v1_min_max_list: list

v2_min_max_list: list

class dct.CircuitParetoDabDesign(circuit_study_name: str, project_directory: str, design_space: CircuitParetoDesignSpace, output_range: CircuitOutputRange, sampling: CircuitSampling, filter: CircuitFilter)

Bases: object

Config to optimize the Dual-Active Bridge (DAB) converter.

circuit_study_name: str

design_space: CircuitParetoDesignSpace

filter: CircuitFilter

output_range: CircuitOutputRange

project_directory: str

sampling: CircuitSampling

class dct.CircuitParetoDesignSpace(f_s_min_max_list: list[int], l_s_min_max_list: list[float], l_1_min_max_list: list[float], l_2__min_max_list: list[float], n_min_max_list: list[float], transistor_1_name_list: list[str], transistor_2_name_list: list[str], c_par_1: float, c_par_2: float)

Bases: object

Definition of the hardware design space for electronic components.

c_par_1: float

c_par_2: float

f_s_min_max_list: list[int]

l_1_min_max_list: list[float]

l_2__min_max_list: list[float]

l_s_min_max_list: list[float]

n_min_max_list: list[float]

transistor_1_name_list: list[str]

transistor_2_name_list: list[str]

class dct.CircuitSampling(sampling_method: SamplingEnum, sampling_points: int, sampling_random_seed: int | None, v1_additional_user_point_list: list[float], v2_additional_user_point_list: list[float], p_additional_user_point_list: list[float], additional_user_weighting_point_list: list[float])

Bases: object

Definition of the sampling method.

additional_user_weighting_point_list: list[float]

p_additional_user_point_list: list[float]

sampling_method: SamplingEnum

sampling_points: int

sampling_random_seed: int | None

v1_additional_user_point_list: list[float]

v2_additional_user_point_list: list[float]

class dct.CondBreakpoints(*, circuit: int, inductor: int, transformer: int, heat_sink: int)

Bases: BaseModel

Flow control conditional breakpoints.

circuit: int

heat_sink: int

inductor: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

transformer: int

class dct.ConfigurationDataEntryDto(configuration_name: str, number_of_trials: int, progress_data: ProgressData)

Bases: object

DTO for queue configuration data information transfer.

configuration_name: str

number_of_trials: int

progress_data: ProgressData

class dct.ConfigurationDataFiles(*, circuit_configuration_file: str, inductor_configuration_file: str, transformer_configuration_file: str, heat_sink_configuration_file: str)

Bases: BaseModel

File paths to the configuration files.

circuit_configuration_file: str

heat_sink_configuration_file: str

inductor_configuration_file: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

transformer_configuration_file: str

class dct.DctMainCtl

Bases: object

Main class for control dab-optimization.

check_breakpoint(break_point_key: str, info: str) → None

Continue, wait for user input or stop the program according breakpoint configuration.

Parameters:

• break_point_key (str) – Breakpoint configuration keyword

• info (str) – Information text displayed at this breakpoint (if program waits or stops).

static check_study_data(study_path: str, study_name: str) → bool

Verify if the study path and sqlite3-database file exists.

Works for all types of studies (circuit, inductor, transformer, heat sink). :param study_path: drive location path to the study :type study_path: str :param study_name: Name of the study :type study_name: str :return: True, if the optimization could be performed successful :rtype: bool

static delete_study_content(folder_name: str, study_file_name: str = '') → None

Delete the study files and the femmt folders.

If a new study is to generate the old obsolete files and folders needs to be deleted.

:param folder_name : Location of the study files :type folder_name : str :param study_file_name : Name of the study files (without extension) :type study_file_name : str

generate_conf_file(path: str) → bool

Create and save the configuration file.

Generate following default configuration files within the path: DabCircuitConf.toml, DabInductorConf.toml, DabTransformerConf.toml and DabHeatSinkConf.toml,

:param path : Location of the configuration :type path : str :return: true, if the files are stored successfully :rtype: bool

static generate_zip_archive(toml_prog_flow: FlowControl) → None

Generate a zip archive from the given simulation results to transfer to another computer.

Remove unnecessary file structure before performing the zip operation, e.g. the 00_femmt_simulation results directory.

Parameters:

toml_prog_flow (tc.FlowControl) – Flow control toml file

static get_initialization_queue_data(act_toml_prog_flow: FlowControl) → tuple[list[ConfigurationDataEntryDto], list[MagneticDataEntryDto], list[ConfigurationDataEntryDto], list[MagneticDataEntryDto], list[ConfigurationDataEntryDto], list[ConfigurationDataEntryDto], list[SummaryDataEntryDto]]

Initialize the lists of configuration data.

Parameters:

act_toml_prog_flow (tc.FlowControl) – Flow control toml file (reference)

Returns:

List of configuration data for data transfer: circuit, transformer, inductor, heat sink and summary. Each configuration gets one entry of the list.

Return type:

list[ConfigurationDataEntryDto], list[srv_ctl_dtos.MagneticDataEntryDto], list[ConfigurationDataEntryDto], list[srv_ctl_dtos.MagneticDataEntryDto], list[ConfigurationDataEntryDto], list[ConfigurationDataEntryDto], list[ConfigurationDataEntryDto], list[SummaryDataEntryDto]

static get_number_of_pkl_files(filtered_file_path: str) → int

Count the number of files with extension ‘pkl’.

If the optimization is skipped the number of filtered points reflected by the number of pkl-files needs to be count for status information.

Parameters:

filtered_file_path (str) – drive location path to the ‘pkl’-file folder

Returns:

Number of pkl-files within the folder corresponds to number of filtered operation points

Return type:

int

static load_generate_logging_config(logging_config_file: str) → None

Read the logging configuration file and configure the logger.

Generate a default logging configuration file in case it does not exist.

Parameters:

logging_config_file (str) – File name of the logging configuration file

static load_toml_file(toml_file: str) → tuple[bool, dict[str, Any]]

Load the toml configuration data to a dictionary.

:param toml_file : File name of the toml-file :type toml_file : str :return: True, if the data could be loaded successful and the loaded dictionary :rtype: bool, dict

static log_software_versions(filepath: str) → None

Log the software versions of selected packages used to generate the results.

Parameters:

filepath (str) – file path and file name of the logging file

run_optimization_from_toml_configurations(workspace_path: str) → None

Perform the main program.

This function corresponds to ‘main’, which is called after the instance of the class are created.

Parameters:

workspace_path (str) – Path to subfolder ‘workspace’ (if empty default path ‘../<path to this file>’ is used)

static set_up_folder_structure(toml_prog_flow: FlowControl) → None

Set up the folder structure for the subprojects.

Parameters:

toml_prog_flow (tc.FlowControl) – Flow control toml file

user_input_break_point(break_point_key: str, info: str) → None

Continue, wait for user input or stop the program according breakpoint configuration.

Parameters:

• break_point_key (str) – Breakpoint configuration keyword

• info (str) – Information text displayed at this breakpoint (if program waits or stops).

class dct.DctServer

Bases: object

Server to visualize the actual progress and calculated Pareto-fronts.

async static admin_page(request: Request, username: str = Depends(get_current_user)) → _TemplateResponse | RedirectResponse

Evaluate the permission of user and return the suitable page.

If the form send by ‘@app.get(“/login”’ send back this method is called. It verify the username and password and provide the suitable evaluation result. :param request: Request information of the client request :type request: Request :param username: Name of the user :type username: str :return: html-page :rtype: _TemplateResponse | RedirectResponse

app = <fastapi.applications.FastAPI object>

break_status: int = 0

async static control_page(request: Request, action: str = '', url_back: str = '/html_homepage1') → _TemplateResponse | HTMLResponse | RedirectResponse

Provide the html-information based on client request to control_page.

Parameters:

• request (Request) – Request information of the client request

• action (str) – Information about the requested action (Keyword driven)

• url_back (str) – Uniform resource locator for jump back

Returns:

html-page

Return type:

_TemplateResponse

static dct_server_thread() → None

Start the FastAPI-server.

static get_circuit_table_data(circuit_data: CircuitConfigurationDataDto) → dict

Fill the table data for display circuit progress data of one configuration with filtered point name.

Parameters:

circuit_data (server_ctl_dtos.CircuitConfigurationDataDto) – Configuration data of circuit configuration for progress reporting

Returns:

Formatted entries of circuit configuration data for progress reporting

Return type:

dict

static get_current_user(request: Request) → Any

Provide the user of the current session.

User of the current session in case of valid login

Parameters:

request (Request) – Request information of the client request

Returns:

User name, if client is logged in, otherwise None

Return type:

Any

static get_format_time(time_value: float) → str

Create the information string based on the input parameters.

The displayed time value is displayed in human understandable way. Depending on thresholds the time is displayed in different way. With the input parameter the information string is generated. :param time_value: time value in second :type time_value: float :return: formatted time value to match the display area :rtype: str

static get_heat_sink_table_data(act_heat_sink_data_list: list[ConfigurationDataEntryDto]) → list[dict]

Fill the table data to display progress based on the configuration progress data.

Parameters:

act_heat_sink_data_list (list[server_ctl_dtos.ConfigurationDataEntryDto]) – List of configuration data for progress reporting

Returns:

List of dict with the formatted entries

Return type:

list[dict]

static get_magnetic_table_data(magnetic_data_list: list[MagneticDataEntryDto]) → list[dict]

Fill the table data for display magnetic progress data of one configuration with filtered point name.

Parameters:

magnetic_data_list (list[server_ctl_dtos.MagneticDataEntryDto]) – Configuration data of magnetic configuration for progress reporting (inductor or transformer)

Returns:

List of formatted entries for progress reporting

Return type:

list[dict]

static get_pareto_front(request: Request, button_index: int | None, table_index: int | None, url_back: str = '') → HTMLResponse

Provide the Pareto-front.

Later to replace by the selected Pareto-front :param request: Request information of the client request :type request: Request :param button_index: Index of selected button, if a button was pressed :type button_index: int :param table_index: Index of selected table in case of a button press :type table_index: int :param url_back: Uniform resource locator for jump back :type url_back: str :return: html-page :rtype: HTMLResponse

static get_summary_table_data(act_summary_data_list: list[SummaryDataEntryDto]) → list[dict]

Fill the table data to display summary progress based on the configuration progress data.

Parameters:

act_summary_data_list (list[server_ctl_dtos.SummaryDataEntryDto]) – List of configuration data for progress reporting

Returns:

List of dict with the formatted entries

Return type:

list[dict]

static get_table_data(component_data_list: list[ConfigurationDataEntryDto]) → list[dict]

Fill the table data to display progress based on the configuration progress data.

Parameters:

component_data_list (list[server_ctl_dtos.ConfigurationDataEntryDto]) – List of configuration data for progress reporting

Returns:

List of dict with the formatted entries

Return type:

list[dict]

icon = ['StyleSheets/OptIdle.png', 'StyleSheets/OptInProgress.png', 'StyleSheets/OptDone.png', 'StyleSheets/OptSkipped.png']

static load_optuna_html_file(filepath: str) → str

Load the optuna file to string.

!!!Later to replace :param filepath: File name inclusive path :type filepath: str :return: file data as string :rtype: str

async static login(request: Request, username: str = Form(PydanticUndefined), password: str = Form(PydanticUndefined)) → _TemplateResponse | RedirectResponse

Evaluate the login data and create a session.

If the form send by ‘@app.get(“/login”’ send back this method is called. It verify the username and password and provide the suitable evaluation result. :param request: Request information of the client request :type request: Request :param username: Name of the user :type username: str :param password: password :type password: str :return: html-page :rtype: _TemplateResponse | RedirectResponse

async static login_page(request: Request) → _TemplateResponse

Provide the html-information based on client request to login_page.

Parameters:

request (Request) – Request information of the client request

Returns:

html-page

Return type:

_TemplateResponse

async static main_page1(request: Request, action: str = '', user: str = Depends(get_current_user), button_index: int | None = None, table_index: int | None = None) → _TemplateResponse | HTMLResponse

Provide the html-information based on client request to html_homepage1.

Parameters:

• request (Request) – Request information of the client request

• action (str) – Information about the requested action (Keyword driven)

• user (str) – User, in case of valid user

• button_index (int) – Index of selected button, if a button was pressed

• table_index (int) – Index of selected table in case of a button press

Returns:

html-page

Return type:

_TemplateResponse | HTMLResponse

async static main_page2(request: Request, action: str = '', c_selected_filtered_point_index: int = -1, user: str | None = Depends(get_current_user), button_index: int | None = None, table_index: int | None = None) → _TemplateResponse | HTMLResponse

Provide the html-information based on client request to html_homepage2.

Parameters:

• request (Request) – Request information of the client request

• action (str) – Information about the requested action (Keyword driven)

• c_selected_filtered_point_index (int) – Index of the selected circuit filtered point

• user (str) – User, in case of valid user

• button_index (int) – Index of selected button, if a button was pressed

• table_index (int) – Index of selected table in case of a button press

Returns:

html-page

Return type:

_TemplateResponse | HTMLResponse

req_stop = <Synchronized wrapper for c_int(0)>

server_object: Server

server_request_queue: Queue

server_response_queue: Queue

server_thread: Thread

static start_dct_server(act_server_request_queue: Queue, act_server_response_queue: Queue, program_exit_flag: bool) → None

Start the server to control and supervise simulation.

Parameters:

• act_server_request_queue (Queue) – Queue object to request data from main process

• act_server_response_queue (Queue) – Queue object to responds to server process

• program_exit_flag (boolean) – Flag, which indicates to terminate the program on request

status_message = 'Wait for button press!'

static stop_dct_server() → None

Stop the server for the control and supervision of the simulation.

stop_flag = <Synchronized wrapper for c_int(0)>

templates = <starlette.templating.Jinja2Templates object>

users = {'Andi': 'hallo'}

class dct.DctSummaryPreProcessing

Bases: object

Perform the summary calculation based on optimization results.

copper_coin_area_1: float

copper_coin_area_2: float

generate_result_database(inductor_study_data: StudyData, transformer_study_data: StudyData, summary_data: StudyData, act_inductor_study_names: list[str], act_stacked_transformer_study_names: list[str], filter_data: FilterData) → DataFrame

Generate a database df by summaries the calculation results.

Parameters:

• inductor_study_data (dct.StudyData) – inductor study data

• transformer_study_data (dct.StudyData) – transformer study data

• summary_data (dct.StudyData) – Information about the summary name and path

• act_inductor_study_names (list[str]) – List of names with inductor studies which are to process

• act_stacked_transformer_study_names (list[str]) – List of names with transformer studies which are to process

• filter_data (dct.FilterData) – filtered result lists

Returns:

DataFrame with result information of the pareto front

Return type:

pd.DataFrame

get_progress_data() → ProgressData

Provide the progress data of the optimization.

Returns:

Progress data: Processing start time, actual processing time, number of filtered operation points and status.

Return type:

ProgressData

heat_sink_boundary_conditions: HeatSinkBoundaryConditions

init_thermal_configuration(act_heat_sink_data: TomlHeatSink) → bool

Initialize the thermal parameter of the connection points for the transistors, inductor and transformer.

Parameters:

act_heat_sink_data (dct.TomlHeatSink) – toml file with configuration data

Returns:

True, if the thermal parameter of the connection points was successful initialized

Return type:

bool

r_th_per_unit_area_ind_heat_sink: float

r_th_per_unit_area_xfmr_heat_sink: float

select_heat_sink_configuration(heat_sink_study_data: StudyData, summary_data: StudyData, act_df_for_hs: DataFrame) → None

Select the heat sink configuration from calculated heat sink pareto front.

Parameters:

• heat_sink_study_data (dct.StudyData) – Information about the heat sink study name and study path

• summary_data (dct.StudyData) – Information about the summary name and path

• act_df_for_hs (pd.DataFrame) – DataFrame with result information of the pareto front for heat sink selection

thr_sup: ThermalCalcSupport

transistor_b1_cooling: TransistorCooling

transistor_b2_cooling: TransistorCooling

class dct.DctSummaryProcessing

Bases: object

Perform the summary calculation based on optimization results.

copper_coin_area_1: float

copper_coin_area_2: float

generate_result_database(inductor_study_data: StudyData, transformer_study_data: StudyData, summary_data: StudyData, act_inductor_study_names: list[str], act_stacked_transformer_study_names: list[str], filter_data: FilterData) → DataFrame

Generate a database df by summaries the calculation results.

Parameters:

• inductor_study_data (dct.StudyData) – inductor study data

• transformer_study_data (dct.StudyData) – transformer study data

• summary_data (dct.StudyData) – Information about the summary name and path

• act_inductor_study_names (list[str]) – List of names with inductor studies which are to process

• act_stacked_transformer_study_names (list[str]) – List of names with transformer studies which are to process

• filter_data (dct.FilterData) – filtered result lists

Returns:

DataFrame with result information of the pareto front

Return type:

pd.DataFrame

get_progress_data() → ProgressData

Provide the progress data of the optimization.

Returns:

Progress data: Processing start time, actual processing time, number of filtered operation points and status.

Return type:

ProgressData

heat_sink_boundary_conditions: HeatSinkBoundaryConditions

init_thermal_configuration(act_heat_sink_data: TomlHeatSink) → bool

Initialize the thermal parameter of the connection points for the transistors, inductor and transformer.

Parameters:

act_heat_sink_data (dct.TomlHeatSink) – toml file with configuration data

Returns:

True, if the thermal parameter of the connection points was successful initialized

Return type:

bool

r_th_per_unit_area_ind_heat_sink: float

r_th_per_unit_area_xfmr_heat_sink: float

select_heat_sink_configuration(heat_sink_study_data: StudyData, summary_data: StudyData, act_df_for_hs: DataFrame) → None

Select the heat sink configuration from calculated heat sink pareto front.

Parameters:

• heat_sink_study_data (dct.StudyData) – Information about the heat sink study name and study path

• summary_data (dct.StudyData) – Information about the summary name and path

• act_df_for_hs (pd.DataFrame) – DataFrame with result information of the pareto front for heat sink selection

thr_sup: ThermalCalcSupport

transistor_b1_cooling: TransistorCooling

transistor_b2_cooling: TransistorCooling

class dct.Debug(*, general: DebugGeneral, inductor: DebugInductor, transformer: DebugTransformer)

Bases: BaseModel

General information in debug configuration.

general: DebugGeneral

inductor: DebugInductor

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

transformer: DebugTransformer

class dct.DebugGeneral(*, is_debug: bool)

Bases: BaseModel

Debug mode general information.

is_debug: bool

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dct.DebugInductor(*, number_reluctance_working_point_max: int, number_fem_working_point_max: int)

Bases: BaseModel

Debug information for the inductor.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_fem_working_point_max: int

number_reluctance_working_point_max: int

class dct.DebugTransformer(*, number_reluctance_working_point_max: int, number_fem_working_point_max: int)

Bases: BaseModel

Debug information for the transformer.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_fem_working_point_max: int

number_reluctance_working_point_max: int

dct.Depends(dependency: Annotated[Callable[[...], Any] | None, Doc('\n            A "dependable" callable (like a function).\n\n            Don\'t call it directly, FastAPI will call it for you, just pass the object\n            directly.\n            ')] = None, *, use_cache: Annotated[bool, Doc('\n            By default, after a dependency is called the first time in a request, if\n            the dependency is declared again for the rest of the request (for example\n            if the dependency is needed by several dependencies), the value will be\n            re-used for the rest of the request.\n\n            Set `use_cache` to `False` to disable this behavior and ensure the\n            dependency is called again (if declared more than once) in the same request.\n            ')] = True) → Any

Declare a FastAPI dependency.

It takes a single “dependable” callable (like a function).

Don’t call it directly, FastAPI will call it for you.

Read more about it in the [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/).

Example

```python from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()

async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):

return {“q”: q, “skip”: skip, “limit”: limit}

@app.get(“/items/”) async def read_items(commons: Annotated[dict, Depends(common_parameters)]):

return commons

```

class dct.Enum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: object

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

• attribute access:

  >>> Color.RED
  <Color.RED: 1>
  

• value lookup:

  >>> Color(1)
  <Color.RED: 1>
  

• name lookup:

  >>> Color['RED']
  <Color.RED: 1>
  

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

class dct.FastAPI(*, debug: ~typing.Annotated[bool, Doc('\n                Boolean indicating if debug tracebacks should be returned on server\n                errors.\n\n                Read more in the\n                [Starlette docs for Applications](https://www.starlette.io/applications/#instantiating-the-application).\n                ')] = False, routes: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                **Note**: you probably shouldn't use this parameter, it is inherited\n                from Starlette and supported for compatibility.\n\n                ---\n\n                A list of routes to serve incoming HTTP and WebSocket requests.\n                "), <typing_extensions.deprecated object at 0x7fab3e512690>] = None, title: ~typing.Annotated[str, Doc('\n                The title of the API.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(title="ChimichangApp")\n                ```\n                ')] = 'FastAPI', summary: ~typing.Annotated[str | None, Doc('\n                A short summary of the API.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(summary="Deadpond\'s favorite app. Nuff said.")\n                ```\n                ')] = None, description: ~typing.Annotated[str, Doc('\n                A description of the API. Supports Markdown (using\n                [CommonMark syntax](https://commonmark.org/)).\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(\n                    description="""\n                                ChimichangApp API helps you do awesome stuff. 🚀\n\n                                ## Items\n\n                                You can **read items**.\n\n                                ## Users\n\n                                You will be able to:\n\n                                * **Create users** (_not implemented_).\n                                * **Read users** (_not implemented_).\n\n                                """\n                )\n                ```\n                ')] = '', version: ~typing.Annotated[str, Doc('\n                The version of the API.\n\n                **Note** This is the version of your application, not the version of\n                the OpenAPI specification nor the version of FastAPI being used.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(version="0.0.1")\n                ```\n                ')] = '0.1.0', openapi_url: ~typing.Annotated[str | None, Doc('\n                The URL where the OpenAPI schema will be served from.\n\n                If you set it to `None`, no OpenAPI schema will be served publicly, and\n                the default automatic endpoints `/docs` and `/redoc` will also be\n                disabled.\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#openapi-url).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(openapi_url="/api/v1/openapi.json")\n                ```\n                ')] = '/openapi.json', openapi_tags: ~typing.Annotated[~typing.List[~typing.Dict[str, ~typing.Any]] | None, Doc('\n                A list of tags used by OpenAPI, these are the same `tags` you can set\n                in the *path operations*, like:\n\n                * `@app.get("/users/", tags=["users"])`\n                * `@app.get("/items/", tags=["items"])`\n\n                The order of the tags can be used to specify the order shown in\n                tools like Swagger UI, used in the automatic path `/docs`.\n\n                It\'s not required to specify all the tags used.\n\n                The tags that are not declared MAY be organized randomly or based\n                on the tools\' logic. Each tag name in the list MUST be unique.\n\n                The value of each item is a `dict` containing:\n\n                * `name`: The name of the tag.\n                * `description`: A short description of the tag.\n                    [CommonMark syntax](https://commonmark.org/) MAY be used for rich\n                    text representation.\n                * `externalDocs`: Additional external documentation for this tag. If\n                    provided, it would contain a `dict` with:\n                    * `description`: A short description of the target documentation.\n                        [CommonMark syntax](https://commonmark.org/) MAY be used for\n                        rich text representation.\n                    * `url`: The URL for the target documentation. Value MUST be in\n                        the form of a URL.\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-tags).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                tags_metadata = [\n                    {\n                        "name": "users",\n                        "description": "Operations with users. The **login** logic is also here.",\n                    },\n                    {\n                        "name": "items",\n                        "description": "Manage items. So _fancy_ they have their own docs.",\n                        "externalDocs": {\n                            "description": "Items external docs",\n                            "url": "https://fastapi.tiangolo.com/",\n                        },\n                    },\n                ]\n\n                app = FastAPI(openapi_tags=tags_metadata)\n                ```\n                ')] = None, servers: ~typing.Annotated[~typing.List[~typing.Dict[str, ~typing.Any | str]] | None, Doc('\n                A `list` of `dict`s with connectivity information to a target server.\n\n                You would use it, for example, if your application is served from\n                different domains and you want to use the same Swagger UI in the\n                browser to interact with each of them (instead of having multiple\n                browser tabs open). Or if you want to leave fixed the possible URLs.\n\n                If the servers `list` is not provided, or is an empty `list`, the\n                default value would be a `dict` with a `url` value of `/`.\n\n                Each item in the `list` is a `dict` containing:\n\n                * `url`: A URL to the target host. This URL supports Server Variables\n                and MAY be relative, to indicate that the host location is relative\n                to the location where the OpenAPI document is being served. Variable\n                substitutions will be made when a variable is named in `{`brackets`}`.\n                * `description`: An optional string describing the host designated by\n                the URL. [CommonMark syntax](https://commonmark.org/) MAY be used for\n                rich text representation.\n                * `variables`: A `dict` between a variable name and its value. The value\n                    is used for substitution in the server\'s URL template.\n\n                Read more in the\n                [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#additional-servers).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(\n                    servers=[\n                        {"url": "https://stag.example.com", "description": "Staging environment"},\n                        {"url": "https://prod.example.com", "description": "Production environment"},\n                    ]\n                )\n                ```\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of global dependencies, they will be applied to each\n                *path operation*, including in sub-routers.\n\n                Read more about it in the\n                [FastAPI docs for Global Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/global-dependencies/).\n\n                **Example**\n\n                ```python\n                from fastapi import Depends, FastAPI\n\n                from .dependencies import func_dep_1, func_dep_2\n\n                app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)])\n                ```\n                ')] = None, default_response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                The default response class to be used.\n\n                Read more in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n                from fastapi.responses import ORJSONResponse\n\n                app = FastAPI(default_response_class=ORJSONResponse)\n                ```\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, redirect_slashes: ~typing.Annotated[bool, Doc('\n                Whether to detect and redirect slashes in URLs when the client doesn\'t\n                use the same format.\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(redirect_slashes=True)  # the default\n\n                @app.get("/items/")\n                async def read_items():\n                    return [{"item_id": "Foo"}]\n                ```\n\n                With this app, if a client goes to `/items` (without a trailing slash),\n                they will be automatically redirected with an HTTP status code of 307\n                to `/items/`.\n                ')] = True, docs_url: ~typing.Annotated[str | None, Doc('\n                The path to the automatic interactive API documentation.\n                It is handled in the browser by Swagger UI.\n\n                The default URL is `/docs`. You can disable it by setting it to `None`.\n\n                If `openapi_url` is set to `None`, this will be automatically disabled.\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#docs-urls).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(docs_url="/documentation", redoc_url=None)\n                ```\n                ')] = '/docs', redoc_url: ~typing.Annotated[str | None, Doc('\n                The path to the alternative automatic interactive API documentation\n                provided by ReDoc.\n\n                The default URL is `/redoc`. You can disable it by setting it to `None`.\n\n                If `openapi_url` is set to `None`, this will be automatically disabled.\n\n                Read more in the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#docs-urls).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(docs_url="/documentation", redoc_url="redocumentation")\n                ```\n                ')] = '/redoc', swagger_ui_oauth2_redirect_url: ~typing.Annotated[str | None, Doc('\n                The OAuth2 redirect endpoint for the Swagger UI.\n\n                By default it is `/docs/oauth2-redirect`.\n\n                This is only used if you use OAuth2 (with the "Authorize" button)\n                with Swagger UI.\n                ')] = '/docs/oauth2-redirect', swagger_ui_init_oauth: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                OAuth2 configuration for the Swagger UI, by default shown at `/docs`.\n\n                Read more about the available configuration options in the\n                [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).\n                ')] = None, middleware: ~typing.Annotated[~typing.Sequence[~starlette.middleware.Middleware] | None, Doc('\n                List of middleware to be added when creating the application.\n\n                In FastAPI you would normally do this with `app.add_middleware()`\n                instead.\n\n                Read more in the\n                [FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/).\n                ')] = None, exception_handlers: ~typing.Annotated[~typing.Dict[int | ~typing.Type[Exception], ~typing.Callable[[~starlette.requests.Request, ~typing.Any], ~typing.Coroutine[~typing.Any, ~typing.Any, ~starlette.responses.Response]]] | None, Doc('\n                A dictionary with handlers for exceptions.\n\n                In FastAPI, you would normally use the decorator\n                `@app.exception_handler()`.\n\n                Read more in the\n                [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/).\n                ')] = None, on_startup: ~typing.Annotated[~typing.Sequence[~typing.Callable[[], ~typing.Any]] | None, Doc('\n                A list of startup event handler functions.\n\n                You should instead use the `lifespan` handlers.\n\n                Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).\n                ')] = None, on_shutdown: ~typing.Annotated[~typing.Sequence[~typing.Callable[[], ~typing.Any]] | None, Doc('\n                A list of shutdown event handler functions.\n\n                You should instead use the `lifespan` handlers.\n\n                Read more in the\n                [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).\n                ')] = None, lifespan: ~typing.Annotated[~typing.Callable[[~fastapi.applications.AppType], ~contextlib.AbstractAsyncContextManager[None]] | ~typing.Callable[[~fastapi.applications.AppType], ~contextlib.AbstractAsyncContextManager[~collections.abc.Mapping[str, ~typing.Any]]] | None, Doc('\n                A `Lifespan` context manager handler. This replaces `startup` and\n                `shutdown` functions with a single context manager.\n\n                Read more in the\n                [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).\n                ')] = None, terms_of_service: ~typing.Annotated[str | None, Doc('\n                A URL to the Terms of Service for your API.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more at the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).\n\n                **Example**\n\n                ```python\n                app = FastAPI(terms_of_service="http://example.com/terms/")\n                ```\n                ')] = None, contact: ~typing.Annotated[~typing.Dict[str, ~typing.Any | str] | None, Doc('\n                A dictionary with the contact information for the exposed API.\n\n                It can contain several fields.\n\n                * `name`: (`str`) The name of the contact person/organization.\n                * `url`: (`str`) A URL pointing to the contact information. MUST be in\n                    the format of a URL.\n                * `email`: (`str`) The email address of the contact person/organization.\n                    MUST be in the format of an email address.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more at the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).\n\n                **Example**\n\n                ```python\n                app = FastAPI(\n                    contact={\n                        "name": "Deadpoolio the Amazing",\n                        "url": "http://x-force.example.com/contact/",\n                        "email": "dp@x-force.example.com",\n                    }\n                )\n                ```\n                ')] = None, license_info: ~typing.Annotated[~typing.Dict[str, ~typing.Any | str] | None, Doc('\n                A dictionary with the license information for the exposed API.\n\n                It can contain several fields.\n\n                * `name`: (`str`) **REQUIRED** (if a `license_info` is set). The\n                    license name used for the API.\n                * `identifier`: (`str`) An [SPDX](https://spdx.dev/) license expression\n                    for the API. The `identifier` field is mutually exclusive of the `url`\n                    field. Available since OpenAPI 3.1.0, FastAPI 0.99.0.\n                * `url`: (`str`) A URL to the license used for the API. This MUST be\n                    the format of a URL.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more at the\n                [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api).\n\n                **Example**\n\n                ```python\n                app = FastAPI(\n                    license_info={\n                        "name": "Apache 2.0",\n                        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",\n                    }\n                )\n                ```\n                ')] = None, openapi_prefix: ~typing.Annotated[str, Doc('\n                A URL prefix for the OpenAPI URL.\n                '), <typing_extensions.deprecated object at 0x7fab3e513860>] = '', root_path: ~typing.Annotated[str, Doc('\n                A path prefix handled by a proxy that is not seen by the application\n                but is seen by external clients, which affects things like Swagger UI.\n\n                Read more about it at the\n                [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(root_path="/api/v1")\n                ```\n                ')] = '', root_path_in_servers: ~typing.Annotated[bool, Doc('\n                To disable automatically generating the URLs in the `servers` field\n                in the autogenerated OpenAPI using the `root_path`.\n\n                Read more about it in the\n                [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#disable-automatic-server-from-root_path).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                app = FastAPI(root_path_in_servers=False)\n                ```\n                ')] = True, responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses to be shown in OpenAPI.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/).\n\n                And in the\n                [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc('\n                OpenAPI callbacks that should apply to all *path operations*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ')] = None, webhooks: ~typing.Annotated[~fastapi.routing.APIRouter | None, Doc("\n                Add OpenAPI webhooks. This is similar to `callbacks` but it doesn't\n                depend on specific *path operations*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                **Note**: This is available since OpenAPI 3.1.0, FastAPI 0.99.0.\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/).\n                ")] = None, deprecated: ~typing.Annotated[bool | None, Doc("\n                Mark all *path operations* as deprecated. You probably don't need it,\n                but it's available.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ")] = None, include_in_schema: ~typing.Annotated[bool, Doc("\n                To include (or not) all the *path operations* in the generated OpenAPI.\n                You probably don't need it, but it's available.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ")] = True, swagger_ui_parameters: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Parameters to configure Swagger UI, the autogenerated interactive API\n                documentation (by default at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, separate_input_output_schemas: ~typing.Annotated[bool, Doc("\n                Whether to generate separate OpenAPI schemas for request body and\n                response body when the results would be more precise.\n\n                This is particularly useful when automatically generating clients.\n\n                For example, if you have a model like:\n\n                ```python\n                from pydantic import BaseModel\n\n                class Item(BaseModel):\n                    name: str\n                    tags: list[str] = []\n                ```\n\n                When `Item` is used for input, a request body, `tags` is not required,\n                the client doesn't have to provide it.\n\n                But when using `Item` for output, for a response body, `tags` is always\n                available because it has a default value, even if it's just an empty\n                list. So, the client should be able to always expect it.\n\n                In this case, there would be two different schemas, one for input and\n                another one for output.\n                ")] = True, **extra: ~typing.Annotated[~typing.Any, Doc('\n                Extra keyword arguments to be stored in the app, not used by FastAPI\n                anywhere.\n                ')])

Bases: Starlette

FastAPI app class, the main entrypoint to use FastAPI.

Read more in the [FastAPI docs for First Steps](https://fastapi.tiangolo.com/tutorial/first-steps/).

## Example

```python from fastapi import FastAPI

app = FastAPI() ```

add_api_route(path: str, endpoint: ~typing.Callable[[...], ~typing.Any], *, response_model: ~typing.Any = <fastapi.datastructures.DefaultPlaceholder object>, status_code: int | None = None, tags: ~typing.List[str | ~enum.Enum] | None = None, dependencies: ~typing.Sequence[~fastapi.params.Depends] | None = None, summary: str | None = None, description: str | None = None, response_description: str = 'Successful Response', responses: ~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None = None, deprecated: bool | None = None, methods: ~typing.List[str] | None = None, operation_id: str | None = None, response_model_include: ~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None = None, response_model_exclude: ~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None = None, response_model_by_alias: bool = True, response_model_exclude_unset: bool = False, response_model_exclude_defaults: bool = False, response_model_exclude_none: bool = False, include_in_schema: bool = True, response_class: ~typing.Type[~starlette.responses.Response] | ~fastapi.datastructures.DefaultPlaceholder = <fastapi.datastructures.DefaultPlaceholder object>, name: str | None = None, openapi_extra: ~typing.Dict[str, ~typing.Any] | None = None, generate_unique_id_function: ~typing.Callable[[~fastapi.routing.APIRoute], str] = <fastapi.datastructures.DefaultPlaceholder object>) → None

add_api_websocket_route(path: str, endpoint: Callable[[...], Any], name: str | None = None, *, dependencies: Sequence[Depends] | None = None) → None

api_route(path: str, *, response_model: ~typing.Any = <fastapi.datastructures.DefaultPlaceholder object>, status_code: int | None = None, tags: ~typing.List[str | ~enum.Enum] | None = None, dependencies: ~typing.Sequence[~fastapi.params.Depends] | None = None, summary: str | None = None, description: str | None = None, response_description: str = 'Successful Response', responses: ~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None = None, deprecated: bool | None = None, methods: ~typing.List[str] | None = None, operation_id: str | None = None, response_model_include: ~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None = None, response_model_exclude: ~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None = None, response_model_by_alias: bool = True, response_model_exclude_unset: bool = False, response_model_exclude_defaults: bool = False, response_model_exclude_none: bool = False, include_in_schema: bool = True, response_class: ~typing.Type[~starlette.responses.Response] = <fastapi.datastructures.DefaultPlaceholder object>, name: str | None = None, openapi_extra: ~typing.Dict[str, ~typing.Any] | None = None, generate_unique_id_function: ~typing.Callable[[~fastapi.routing.APIRoute], str] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

delete(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP DELETE operation.

## Example

```python from fastapi import FastAPI

app = FastAPI()

@app.delete(“/items/{item_id}”) def delete_item(item_id: str):

return {“message”: “Item deleted”}

```

exception_handler(exc_class_or_status_code: Annotated[int | Type[Exception], Doc('\n                The Exception class this would handle, or a status code.\n                ')]) → Callable[[DecoratedCallable], DecoratedCallable]

Add an exception handler to the app.

Read more about it in the [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/).

## Example

```python from fastapi import FastAPI, Request from fastapi.responses import JSONResponse

class UnicornException(Exception):

def __init__(self, name: str):

self.name = name

app = FastAPI()

@app.exception_handler(UnicornException) async def unicorn_exception_handler(request: Request, exc: UnicornException):

return JSONResponse(

status_code=418, content={“message”: f”Oops! {exc.name} did something. There goes a rainbow…”},

)

```

get(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP GET operation.

## Example

```python from fastapi import FastAPI

app = FastAPI()

@app.get(“/items/”) def read_items():

return [{“name”: “Empanada”}, {“name”: “Arepa”}]

```

head(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP HEAD operation.

## Example

```python from fastapi import FastAPI, Response

app = FastAPI()

@app.head(“/items/”, status_code=204) def get_items_headers(response: Response):

response.headers[“X-Cat-Dog”] = “Alone in the world”

```

include_router(router: ~typing.Annotated[~fastapi.routing.APIRouter, Doc('The `APIRouter` to include.')], *, prefix: ~typing.Annotated[str, Doc('An optional path prefix for the router.')] = '', tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to all the *path operations* in this\n                router.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to all the\n                *path operations* in this router.\n\n                Read more about it in the\n                [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).\n\n                **Example**\n\n                ```python\n                from fastapi import Depends, FastAPI\n\n                from .dependencies import get_token_header\n                from .internal import admin\n\n                app = FastAPI()\n\n                app.include_router(\n                    admin.router,\n                    dependencies=[Depends(get_token_header)],\n                )\n                ```\n                ')] = None, responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses to be shown in OpenAPI.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/).\n\n                And in the\n                [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark all the *path operations* in this router as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                from .internal import old_api\n\n                app = FastAPI()\n\n                app.include_router(\n                    old_api.router,\n                    deprecated=True,\n                )\n                ```\n                ')] = None, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include (or not) all the *path operations* in this router in the\n                generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n\n                from .internal import old_api\n\n                app = FastAPI()\n\n                app.include_router(\n                    old_api.router,\n                    include_in_schema=False,\n                )\n                ```\n                ')] = True, default_response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Default response class to be used for the *path operations* in this\n                router.\n\n                Read more in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).\n\n                **Example**\n\n                ```python\n                from fastapi import FastAPI\n                from fastapi.responses import ORJSONResponse\n\n                from .internal import old_api\n\n                app = FastAPI()\n\n                app.include_router(\n                    old_api.router,\n                    default_response_class=ORJSONResponse,\n                )\n                ```\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → None

Include an APIRouter in the same app.

Read more about it in the [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/).

## Example

```python from fastapi import FastAPI

from .users import users_router

app = FastAPI()

app.include_router(users_router) ```

middleware(middleware_type: Annotated[str, Doc('\n                The type of middleware. Currently only supports `http`.\n                ')]) → Callable[[DecoratedCallable], DecoratedCallable]

Add a middleware to the application.

Read more about it in the [FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/).

## Example

```python import time from typing import Awaitable, Callable

from fastapi import FastAPI, Request, Response

app = FastAPI()

@app.middleware(“http”) async def add_process_time_header(

request: Request, call_next: Callable[[Request], Awaitable[Response]]

) -> Response:

start_time = time.time() response = await call_next(request) process_time = time.time() - start_time response.headers[“X-Process-Time”] = str(process_time) return response

```

on_event(event_type: Annotated[str, Doc('\n                The type of event. `startup` or `shutdown`.\n                ')]) → Callable[[DecoratedCallable], DecoratedCallable]

Add an event handler for the application.

on_event is deprecated, use lifespan event handlers instead.

Read more about it in the [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated).

openapi() → Dict[str, Any]

Generate the OpenAPI schema of the application. This is called by FastAPI internally.

The first time it is called it stores the result in the attribute app.openapi_schema, and next times it is called, it just returns that same result. To avoid the cost of generating the schema every time.

If you need to modify the generated OpenAPI schema, you could modify it.

Read more in the [FastAPI docs for OpenAPI](https://fastapi.tiangolo.com/how-to/extending-openapi/).

options(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP OPTIONS operation.

## Example

```python from fastapi import FastAPI

app = FastAPI()

@app.options(“/items/”) def get_item_options():

return {“additions”: [“Aji”, “Guacamole”]}

```

patch(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP PATCH operation.

## Example

```python from fastapi import FastAPI from pydantic import BaseModel

class Item(BaseModel):

name: str description: str | None = None

app = FastAPI()

@app.patch(“/items/”) def update_item(item: Item):

return {“message”: “Item updated in place”}

```

post(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP POST operation.

## Example

```python from fastapi import FastAPI from pydantic import BaseModel

class Item(BaseModel):

name: str description: str | None = None

app = FastAPI()

@app.post(“/items/”) def create_item(item: Item):

return {“message”: “Item created”}

```

put(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP PUT operation.

## Example

```python from fastapi import FastAPI from pydantic import BaseModel

class Item(BaseModel):

name: str description: str | None = None

app = FastAPI()

@app.put(“/items/{item_id}”) def replace_item(item_id: str, item: Item):

return {“message”: “Item replaced”, “id”: item_id}

```

setup() → None

trace(path: ~typing.Annotated[str, Doc('\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                ')], *, response_model: ~typing.Annotated[~typing.Any, Doc("\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                ")] = <fastapi.datastructures.DefaultPlaceholder object>, status_code: ~typing.Annotated[int | None, Doc('\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                ')] = None, tags: ~typing.Annotated[~typing.List[str | ~enum.Enum] | None, Doc('\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                ')] = None, dependencies: ~typing.Annotated[~typing.Sequence[~fastapi.params.Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                ')] = None, summary: ~typing.Annotated[str | None, Doc('\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, description: ~typing.Annotated[str | None, Doc('\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                ')] = None, response_description: ~typing.Annotated[str, Doc('\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = 'Successful Response', responses: ~typing.Annotated[~typing.Dict[int | str, ~typing.Dict[str, ~typing.Any]] | None, Doc('\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, deprecated: ~typing.Annotated[bool | None, Doc('\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                ')] = None, operation_id: ~typing.Annotated[str | None, Doc('\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = None, response_model_include: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_exclude: ~typing.Annotated[~typing.Set[int] | ~typing.Set[str] | ~typing.Dict[int, ~typing.Any] | ~typing.Dict[str, ~typing.Any] | None, Doc('\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = None, response_model_by_alias: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                ')] = True, response_model_exclude_unset: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_defaults: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                ')] = False, response_model_exclude_none: ~typing.Annotated[bool, Doc('\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                ')] = False, include_in_schema: ~typing.Annotated[bool, Doc('\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).\n                ')] = True, response_class: ~typing.Annotated[~typing.Type[~starlette.responses.Response], Doc('\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>, name: ~typing.Annotated[str | None, Doc('\n                Name for this *path operation*. Only used internally.\n                ')] = None, callbacks: ~typing.Annotated[~typing.List[~starlette.routing.BaseRoute] | None, Doc("\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                ")] = None, openapi_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                ')] = None, generate_unique_id_function: ~typing.Annotated[~typing.Callable[[~fastapi.routing.APIRoute], str], Doc('\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                ')] = <fastapi.datastructures.DefaultPlaceholder object>) → Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP TRACE operation.

## Example

```python from fastapi import FastAPI

app = FastAPI()

@app.trace(“/items/{item_id}”) def trace_item(item_id: str):

return None

```

websocket(path: Annotated[str, Doc('\n                WebSocket path.\n                ')], name: Annotated[str | None, Doc('\n                A name for the WebSocket. Only used internally.\n                ')] = None, *, dependencies: Annotated[Sequence[Depends] | None, Doc('\n                A list of dependencies (using `Depends()`) to be used for this\n                WebSocket.\n\n                Read more about it in the\n                [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).\n                ')] = None) → Callable[[DecoratedCallable], DecoratedCallable]

Decorate a WebSocket function.

Read more about it in the [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).

Example

```python from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket(“/ws”) async def websocket_endpoint(websocket: WebSocket):

await websocket.accept() while True:

data = await websocket.receive_text() await websocket.send_text(f”Message text was: {data}”)

```

websocket_route(path: str, name: str | None = None) → Callable[[DecoratedCallable], DecoratedCallable]

We no longer document this decorator style API, and its usage is discouraged. Instead you should use the following approach:

>>> routes = [WebSocketRoute(path, endpoint=...), ...]
>>> app = Starlette(routes=routes)

class dct.FilterData(filtered_list_files: list[str], filtered_list_pathname: str, circuit_study_name: str)

Bases: object

Information about the filtered circuit designs.

circuit_study_name: str

filtered_list_files: list[str]

filtered_list_pathname: str

class dct.FixedParameters(transistor_1_dto_list: list[TransistorDTO], transistor_2_dto_list: list[TransistorDTO], mesh_v1: ndarray, mesh_v2: ndarray, mesh_p: ndarray, mesh_weights: ndarray)

Bases: object

Fixed parameters for the circuit optimization.

mesh_p: ndarray

mesh_v1: ndarray

mesh_v2: ndarray

mesh_weights: ndarray

transistor_1_dto_list: list[TransistorDTO]

transistor_2_dto_list: list[TransistorDTO]

class dct.FlowControl(*, general: General, breakpoints: Breakpoints, conditional_breakpoints: CondBreakpoints, circuit: Circuit, inductor: Inductor, transformer: Transformer, heat_sink: HeatSink, pre_summary: PreSummary, summary: Summary, configuration_data_files: ConfigurationDataFiles)

Bases: BaseModel

General flow control class.

breakpoints: Breakpoints

circuit: Circuit

conditional_breakpoints: CondBreakpoints

configuration_data_files: ConfigurationDataFiles

general: General

heat_sink: HeatSink

inductor: Inductor

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pre_summary: PreSummary

summary: Summary

transformer: Transformer

dct.Form(default: ~typing.Annotated[~typing.Any, Doc('\n            Default value if the parameter field is not set.\n            ')] = PydanticUndefined, *, default_factory: ~typing.Annotated[~typing.Callable[[], ~typing.Any] | None, Doc("\n            A callable to generate the default value.\n\n            This doesn't affect `Path` parameters as the value is always required.\n            The parameter is available only for compatibility.\n            ")] = PydanticUndefined, media_type: ~typing.Annotated[str, Doc("\n            The media type of this parameter field. Changing it would affect the\n            generated OpenAPI, but currently it doesn't affect the parsing of the data.\n            ")] = 'application/x-www-form-urlencoded', alias: ~typing.Annotated[str | None, Doc("\n            An alternative name for the parameter field.\n\n            This will be used to extract the data and for the generated OpenAPI.\n            It is particularly useful when you can't use the name you want because it\n            is a Python reserved keyword or similar.\n            ")] = None, alias_priority: ~typing.Annotated[int | None, Doc('\n            Priority of the alias. This affects whether an alias generator is used.\n            ')] = PydanticUndefined, validation_alias: ~typing.Annotated[str | None, Doc("\n            'Whitelist' validation step. The parameter field will be the single one\n            allowed by the alias or set of aliases defined.\n            ")] = None, serialization_alias: ~typing.Annotated[str | None, Doc("\n            'Blacklist' validation step. The vanilla parameter field will be the\n            single one of the alias' or set of aliases' fields and all the other\n            fields will be ignored at serialization time.\n            ")] = None, title: ~typing.Annotated[str | None, Doc('\n            Human-readable title.\n            ')] = None, description: ~typing.Annotated[str | None, Doc('\n            Human-readable description.\n            ')] = None, gt: ~typing.Annotated[float | None, Doc('\n            Greater than. If set, value must be greater than this. Only applicable to\n            numbers.\n            ')] = None, ge: ~typing.Annotated[float | None, Doc('\n            Greater than or equal. If set, value must be greater than or equal to\n            this. Only applicable to numbers.\n            ')] = None, lt: ~typing.Annotated[float | None, Doc('\n            Less than. If set, value must be less than this. Only applicable to numbers.\n            ')] = None, le: ~typing.Annotated[float | None, Doc('\n            Less than or equal. If set, value must be less than or equal to this.\n            Only applicable to numbers.\n            ')] = None, min_length: ~typing.Annotated[int | None, Doc('\n            Minimum length for strings.\n            ')] = None, max_length: ~typing.Annotated[int | None, Doc('\n            Maximum length for strings.\n            ')] = None, pattern: ~typing.Annotated[str | None, Doc('\n            RegEx pattern for strings.\n            ')] = None, regex: ~typing.Annotated[str | None, Doc('\n            RegEx pattern for strings.\n            '), <typing_extensions.deprecated object at 0x7fab3e6a6990>] = None, discriminator: ~typing.Annotated[str | None, Doc('\n            Parameter field name for discriminating the type in a tagged union.\n            ')] = None, strict: ~typing.Annotated[bool | None, Doc('\n            If `True`, strict validation is applied to the field.\n            ')] = PydanticUndefined, multiple_of: ~typing.Annotated[float | None, Doc('\n            Value must be a multiple of this. Only applicable to numbers.\n            ')] = PydanticUndefined, allow_inf_nan: ~typing.Annotated[bool | None, Doc('\n            Allow `inf`, `-inf`, `nan`. Only applicable to numbers.\n            ')] = PydanticUndefined, max_digits: ~typing.Annotated[int | None, Doc('\n            Maximum number of allow digits for strings.\n            ')] = PydanticUndefined, decimal_places: ~typing.Annotated[int | None, Doc('\n            Maximum number of decimal places allowed for numbers.\n            ')] = PydanticUndefined, examples: ~typing.Annotated[~typing.List[~typing.Any] | None, Doc('\n            Example values for this field.\n            ')] = None, example: ~typing.Annotated[~typing.Any | None, <typing_extensions.deprecated object at 0x7fab3e6a6a80>] = PydanticUndefined, openapi_examples: ~typing.Annotated[~typing.Dict[str, ~fastapi.openapi.models.Example] | None, Doc("\n            OpenAPI-specific examples.\n\n            It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n            Swagger UI (that provides the `/docs` interface) has better support for the\n            OpenAPI-specific examples than the JSON Schema `examples`, that's the main\n            use case for this.\n\n            Read more about it in the\n            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).\n            ")] = None, deprecated: ~typing.Annotated[~typing_extensions.deprecated | str | bool | None, Doc('\n            Mark this parameter field as deprecated.\n\n            It will affect the generated OpenAPI (e.g. visible at `/docs`).\n            ')] = None, include_in_schema: ~typing.Annotated[bool, Doc("\n            To include (or not) this parameter field in the generated OpenAPI.\n            You probably don't need it, but it's available.\n\n            This affects the generated OpenAPI (e.g. visible at `/docs`).\n            ")] = True, json_schema_extra: ~typing.Annotated[~typing.Dict[str, ~typing.Any] | None, Doc('\n            Any additional JSON schema data.\n            ')] = None, **extra: ~typing.Annotated[~typing.Any, Doc('\n            Include extra fields used by the JSON Schema.\n            '), <typing_extensions.deprecated object at 0x7fab3e6a6ba0>]) → Any

class dct.GeckoAdditionalParameters(**kwargs)

Bases: object

Additional parameters for the GeckoCIRCUITS simulation, like simulation time or some file paths.

lossfilepath: str

number_pre_sim_periods: int

number_sim_periods: int

simfilepath: str

t_dead1: ndarray

t_dead2: ndarray

timestep: float64

timestep_pre: float64

class dct.GeckoResults(**kwargs)

Bases: object

DTO contains the result of the GeckoCIRCUITS simulation.

I1_squared_total_mean: ndarray

S11_p_cond: ndarray

S11_p_sw: ndarray

S12_p_cond: ndarray

S12_p_sw: ndarray

S23_p_cond: ndarray

S23_p_sw: ndarray

S24_p_cond: ndarray

S24_p_sw: ndarray

i_C11: ndarray

i_C12: ndarray

i_C23: ndarray

i_C24: ndarray

i_HF1: ndarray

i_HF1_S11_sw_on: ndarray

i_HF1_total_mean: ndarray

i_HF2: ndarray

i_HF2_S23_sw_on: ndarray

i_Lc1: ndarray

i_Lc2: ndarray

i_Ls: ndarray

i_S11: ndarray

i_S12: ndarray

i_S23: ndarray

i_S24: ndarray

i_dc1: ndarray

i_dc2: ndarray

p_cond1: ndarray

p_cond2: ndarray

p_dc1: ndarray

p_dc2: ndarray

p_sw1: ndarray

p_sw2: ndarray

power_deviation: ndarray

v_dc1: ndarray

v_dc2: ndarray

v_ds_S11_sw_on: ndarray

v_ds_S23_sw_on: ndarray

zvs_coverage: ndarray

zvs_coverage1: ndarray

zvs_coverage1_notnan: ndarray

zvs_coverage2: ndarray

zvs_coverage2_notnan: ndarray

zvs_coverage_notnan: ndarray

class dct.GeckoWaveforms(**kwargs)

Bases: object

DTO contains the waveform result of the GeckoCIRCUITS simulation.

i_HF1: ndarray

i_HF2: ndarray

i_Lc1: ndarray

i_Lc2: ndarray

i_Ls: ndarray

time: ndarray

class dct.General(*, project_directory: str)

Bases: BaseModel

General flow control information.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

project_directory: str

class dct.HTMLResponse(content: Any = None, status_code: int = 200, headers: Mapping[str, str] | None = None, media_type: str | None = None, background: BackgroundTask | None = None)

Bases: Response

media_type = 'text/html'

class dct.HandleDabDto

Bases: object

Class to handle the DabDTO, e.g. save and load the files.

static add_gecko_simulation_results(dab_dto: CircuitDabDTO, get_waveforms: bool = False) → CircuitDabDTO

Add GeckoCIRCUITS simulation results to the given DTO.

Parameters:

• dab_dto – DabDTO

• get_waveforms (bool) – Read back GeckoCIRCUITS simulation waveforms (high memory consumption). Default to False.

Returns:

DabDTO

static add_inductor_results(dab_dto: CircuitDabDTO, inductor_results: InductorResults) → CircuitDabDTO

Add inductor results to the CircuitDabDTO.

Parameters:

• dab_dto (d_dtos.CircuitDabDTO) – Dual-active bridge DTO

• inductor_results (InductorResults) – inductor losses

Returns:

Dual-active bridge DTO including the inductor losses

Return type:

d_dtos.CircuitDabDTO

static add_stacked_transformer_results(dab_dto: CircuitDabDTO, transformer_results: StackedTransformerResults) → CircuitDabDTO

Add stacked transformer results to the CircuitDabDTO.

Parameters:

• dab_dto (d_dtos.CircuitDabDTO) – Dual-active bridge DTO

• transformer_results (StackedTransformerResults) – stacked transformer results

Returns:

Dual-active bridge DTO including the inductor losses

Return type:

d_dtos.CircuitDabDTO

static calculate_from_configuration(config: CircuitConfig) → CalcFromCircuitConfig

Calculate logical parameters which can be calculated from the input parameters.

Parameters:

config (CircuitConfig) – DAB configuration

Returns:

CalcFromConfig

Return type:

CalcFromCircuitConfig

static calculate_modulation(config: CircuitConfig, calc_config: CalcFromCircuitConfig) → CalcModulation

Calculate the modulation parameters like phi, tau1, tau, …

Parameters:

• config – DAB input configuration

• calc_config – calculated parameters from the input configuration

Returns:

Modulation parameters.

static export_transformer_target_parameters_dto(dab_dto: CircuitDabDTO) → TransformerTargetParameters

Export the optimization parameters for the transformer optimization (inside FEMMT).

Note: the current counting system is adapted to FEMMT! The secondary current is counted negative!

Parameters:

dab_dto (d_dtos.CircuitDabDTO) – DAB DTO

Returns:

DTO for the transformer optimization using FEMMT

Return type:

TransformerTargetParameters

static get_c_oss_from_tdb(transistor: Transistor, margin_factor: float = 1.2) → tuple

Import the transistor Coss(Vds) capacitance from the transistor database (TDB).

Note we assume V_ds in Volt and C_oss in F. If this is not the case, scale your data accordingly!

Parameters:

• transistor (transistordatabase.Transistor) – transistor database object

• margin_factor (float) – factor for margin. [1.0 = no margin], [1.2 = 20 % margin: DEFAULT]

Returns:

c_oss, q_oss (in 1 V steps)

Return type:

tuple

static get_max_peak_waveform_inductor(dab_dto: CircuitDabDTO, plot: bool = False) → tuple[ndarray, ndarray]

Get the inductor waveform with the maximum current peak out of the three-dimensional simulation array (v_1, v_2, P).

Parameters:

• dab_dto (d_dtos.CircuitDabDTO) – DAB data transfer object (DTO)

• plot (bool) – True to plot the results, mostly for understanding and debugging

Returns:

sorted_max_angles, i_l_s_max_current_waveform, i_l1_max_current_waveform. All as a numpy array.

Return type:

List[np.ndarray]

static get_max_peak_waveform_transformer(dab_dto: CircuitDabDTO, plot: bool = False) → tuple[ndarray, ndarray, ndarray]

Get the transformer waveform with the maximum current peak out of the three-dimensional simulation array (v_1, v_2, P).

Parameters:

• dab_dto (d_dtos.CircuitDabDTO) – DAB data transfer object (DTO)

• plot (bool) – True to plot the results, mostly for understanding and debugging

Returns:

sorted_max_angles, i_l_s_max_current_waveform, i_hf_2_max_current_waveform. All as a numpy array.

Return type:

List[np.ndarray]

static init_config(name: str, mesh_v1: ndarray, mesh_v2: ndarray, mesh_p: ndarray, sampling: CircuitSampling, n: float, ls: float, lc1: float, lc2: float, fs: float, transistor_dto_1: TransistorDTO, transistor_dto_2: TransistorDTO, c_par_1: float, c_par_2: float) → CircuitDabDTO

Initialize the DAB structure.

Parameters:

• name (str) – name of the simulation

• mesh_v1 (np.ndarray) – mesh or hypercube sampling for v1

• mesh_v2 (np.ndarray) – mesh or hypercube sampling for v2

• mesh_p (np.ndarray) – mesh or hypercube sampling for p

• sampling (d_dtos.Sampling) – Sampling parameters

• n (float) – transformer transfer ratio

• ls (float) – series inductance

• lc1 (float) – Commutation inductance Lc1

• lc2 (float) – Commutation inductance Lc2

• fs (float) – Switching frequency

• transistor_dto_1 (TransistorDTO) – Transistor DTO for transistor bridge 1. Must match with transistordatabase available transistors.

• transistor_dto_2 (TransistorDTO) – Transistor DTO for transistor bridge 2. Must match with transistordatabase available transistors.

• c_par_1 (float) – Parasitic PCB capacitance per transistor footprint of bridge 1

• c_par_2 (float) – Parasitic PCB capacitance per transistor footprint of bridge 2

Returns:

static load_from_file(file: str) → CircuitDabDTO

Load everything from the given .npz file.

Parameters:

file – a .nps filename or file-like object, string, or pathlib.Path

Returns:

two objects with type DAB_Specification and DAB_Results

static save(dab_dto: CircuitDabDTO, name: str, directory: str, timestamp: bool = True) → None

Save the DabDTO-class to a npz file.

Parameters:

• dab_dto (d_dtos.CircuitDabDTO) – Class to store

• name (str) – Filename

• directory (str) – Directory to store the results

• timestamp (bool) – [True] to add a timestamp to the file name.

class dct.HandleTransistorDto

Bases: object

Handle the transistor DTOs.

static tdb_to_transistor_dto(transistor_name: str, c_oss_margin_factor: float = 1.2) → TransistorDTO

Load a transistor from the transistor database and transfer the important parameters to a TransistorDTO.

Parameters:

• transistor_name (str) – transistor name, must be same name as in the transistor database

• c_oss_margin_factor (float) – margin for c_oss

Returns:

Transistor DTO

Return type:

d_dtosTransistorDTO

class dct.HeatSink(*, number_of_trials: int, calculation_mode: Literal['new', 'continue', 'skip'], subdirectory: str)

Bases: BaseModel

Flow control for the heat sink.

calculation_mode: Literal['new', 'continue', 'skip']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_of_trials: int

subdirectory: str

class dct.HeatSinkBoundaryConditions(t_ambient: float, t_hs_max: float)

Bases: object

Fix parameters for the heat sink cooling.

t_ambient: float

t_hs_max: float

class dct.HeatSinkOptimization

Bases: object

Optimization support class for heat sink optimization.

get_progress_data() → ProgressData

Provide the progress data of the optimization.

Returns:

Progress data: Processing start time, actual processing time and status. number of filtered heat sink Pareto front points are obsolete

Return type:

ProgressData

initialize_heat_sink_optimization(toml_heat_sink: TomlHeatSink, toml_prog_flow: FlowControl) → bool

Initialize the configuration.

Parameters:

• toml_heat_sink (dct.TomlHeatSink) – toml heat sink class

• toml_prog_flow (dct.FlowControl) – toml program flow class

Returns:

True, if the configuration was successful initialized

Return type:

bool

optimization_handler(target_number_trials: int, debug: bool = False) → None

Control the multi simulation processes.

Parameters:

• target_number_trials (int) – Number of trials for the optimization

• debug (bool) – Debug mode flag

static verify_optimization_parameter(toml_heat_sink: TomlHeatSink) → tuple[bool, str]

Verify the input parameter ranges.

Parameters:

toml_heat_sink (dct.TomlInductor) – toml inductor configuration

Returns:

True, if the configuration was consistent

Return type:

bool

class dct.Inductor(*, number_of_trials: int, calculation_mode: Literal['new', 'continue', 'skip'], subdirectory: str)

Bases: BaseModel

Flow control for the inductor.

calculation_mode: Literal['new', 'continue', 'skip']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_of_trials: int

subdirectory: str

class dct.InductorOptimization

Bases: object

Optimization of the inductor.

fem_simulation_handler(filter_data: FilterData, factor_dc_losses_min_max_list: list[float] | None, debug: Debug) → None

Control the multi simulation processes.

Parameters:

• filter_data (dct.FilterData) – Information about the filtered designs

• factor_dc_losses_min_max_list (float) – Filter factor for min and max losses to use filter the results

• debug (dct.Debug) – Debug DTO

get_number_of_performed_calculations() → int

Provide the number of performed calculations.

Returns:

int: Number of performed calculations

Return type:

int

get_progress_data(filtered_list_id: int) → ProgressData

Provide the progress data of the optimization.

Parameters:

filtered_list_id (int) – List index of the filtered operation point from circuit

Returns:

Progress data: Processing start time, actual processing time, number of filtered inductor Pareto front points and status.

Return type:

ProgressData

initialize_inductor_optimization_list(toml_inductor: TomlInductor, study_data: StudyData, circuit_filter_data: FilterData) → bool

Generate the input geometry/settings list for the FEM simulation.

Parameters:

• toml_inductor (dct.TomlInductor) – toml inductor configuration

• study_data (dct.StudyData) – study data

• circuit_filter_data (dct.FilterData) – Information about the filtered circuit designs

Returns:

True, if the configuration was successful initialized

Return type:

bool

optimization_handler_reluctance_model(filter_data: FilterData, target_number_trials: int, factor_dc_losses_min_max_list: list[float] | None, debug: Debug) → None

Control the multi simulation processes.

Parameters:

• filter_data (dct.FilterData) – Information about the filtered designs

• target_number_trials (int) – Number of trials for the optimization

• factor_dc_losses_min_max_list (float) – Filter factor for min and max losses to use filter the results

• debug (bool) – True to use debug mode which stops earlier

static verify_optimization_parameter(toml_inductor: TomlInductor) → tuple[bool, str]

Verify the input parameter ranges.

Parameters:

toml_inductor (dct.TomlInductor) – toml inductor configuration

Returns:

True, if the configuration was consistent

Return type:

bool

class dct.InductorOptimizationDto(circuit_filtered_point_filename: str, progress_data: ProgressData, inductor_optimization_dto: InductorOptimizationDTO)

Bases: object

DTO for the inductor optimization.

circuit_filtered_point_filename: str

inductor_optimization_dto: InductorOptimizationDTO

progress_data: ProgressData

class dct.InductorResults(**kwargs)

Bases: object

DTO contains the inductor losses.

area_to_heat_sink: float

circuit_trial_file: str

inductor_trial_number: int

p_combined_losses: ndarray

volume: float

class dct.Jinja2Templates(directory: str | PathLike[str] | Sequence[str | PathLike[str]], *, context_processors: list[Callable[[Request], dict[str, Any]]] | None = None, **env_options: Any)

class dct.Jinja2Templates(*, env: Environment, context_processors: list[Callable[[Request], dict[str, Any]]] | None = None)

Bases: object

templates = Jinja2Templates(“templates”)

return templates.TemplateResponse(“index.html”, {“request”: request})

TemplateResponse(*args: Any, **kwargs: Any) → _TemplateResponse

get_template(name: str) → Template

class dct.MagneticDataEntryDto(magnetic_configuration_name: str, number_calculations: int, number_performed_calculations: int, progress_data: ProgressData)

Bases: object

DTO for queue summary information transfer.

magnetic_configuration_name: str

number_calculations: int

number_performed_calculations: int

progress_data: ProgressData

class dct.MagneticElementCooling(tim_conductivity: float, tim_thickness: float)

Bases: object

Fix parameters for the magnetic element cooling.

tim_conductivity: float

tim_thickness: float

class dct.ParetoFilePaths(circuit: str, inductor: str, transformer: str, heat_sink: str)

Bases: object

File paths for the sub simulation optimization parts.

circuit: str

heat_sink: str

inductor: str

transformer: str

class dct.ParetoFrontSource(*values)

Bases: Enum

Enum of Pareto front types.

pareto_circuit = 0

pareto_heat_sink = 3

pareto_inductor = 1

pareto_summary = 4

pareto_transformer = 2

class dct.ParetoPlots

Bases: object

Generate PDF plots to see the results of single Pareto steps (circuit, inductor, transformer, heat sink).

static generate_pdf_pareto(x_values_list: list, y_values_list: list, color_list: list, alpha: float, x_label: str, y_label: str, label_list: list[str | None], fig_name: str, xlim: list | None = None, ylim: list | None = None) → None

Generate multiple Pareto plot in one PDF file.

Parameters:

• x_values_list (list) – list of different Pareto plot x values

• y_values_list (list) – list of different Pareto plot y values

• color_list

• alpha (float) – The alpha blending value, between 0 (transparent) and 1 (opaque).

• x_label (str) – x label of the Pareto plot

• y_label (str) – y label of the Pareto plot

• label_list (list[str | None]) – list of different Pareto plot labels in a legend

• fig_name (str) – filename, will be saved as pdf

• xlim (list[float]) – x-axis limitation [x_min, x_max]

• ylim (list[float]) – y-axis limitation [y_min, y_max]

static plot_circuit_results(toml_prog_flow: FlowControl, is_pre_summary: bool = False) → None

Plot the results of the circuit optimization in the Pareto plane.

Parameters:

• toml_prog_flow (tc.FlowControl) – Flow control toml file

• is_pre_summary (bool) – True to store the results in the pre_summary directory

static plot_heat_sink_results(toml_prog_flow: FlowControl, is_pre_summary: bool = False) → None

Plot the results of the heat sink optimization in the Pareto plane.

Parameters:

• toml_prog_flow (tc.FlowControl) – Flow control toml file

• is_pre_summary (bool) – True to store the results in the pre_summary directory

static plot_inductor_results(toml_prog_flow: FlowControl, is_pre_summary: bool = False) → None

Plot the results of the inductor optimization in the Pareto plane.

Parameters:

• toml_prog_flow (tc.FlowControl) – Flow control toml file

• is_pre_summary (bool) – True to store the results in the pre_summary directory

static plot_summary(toml_prog_flow: FlowControl, is_pre_summary: bool = False) → None

Plot the combined results of circuit, inductor, transformer and heat sink in the Pareto plane.

Parameters:

• toml_prog_flow (tc.FlowControl) – Flow control toml file

• is_pre_summary (bool) – True to store the results in the pre_summary directory

static plot_transformer_results(toml_prog_flow: FlowControl, is_pre_summary: bool = False) → None

Plot the results of the transformer optimization in the Pareto plane.

Parameters:

• toml_prog_flow (tc.FlowControl) – Flow control toml file

• is_pre_summary (bool) – True to store the results in the pre_summary directory

static read_circuit_numbers_from_filestructure(toml_prog_flow: FlowControl) → list[str]

Get the filtered circuit numbers from the “filtered_results” folder.

Parameters:

toml_prog_flow (tc.FlowControl) – Flow control toml file

Returns:

List with number of filtered circuit simulations

Return type:

list[int]

class dct.PlotDAB(is_latex: bool = False, window_title: str = 'DAB Plots', figsize: tuple = (12, 5), fontsize: int = 16, show: bool = True)

Bases: object

Class storing and managing the plot window, figs and axes.

apply_spacings(fig)

Set default spacings for the plots.

Parameters:

fig (matplotlib.plot.figure) – matplotlib figure

close()

Close plot window.

figs_axes: list

new_fig(nrows: int = 1, ncols: int = 1, sharex: bool = True, sharey: bool = True, tab_title: str = 'add Plot title') → None

Create a new fig in a new tab with the amount of subplots specified.

Parameters:

• nrows (int) – number of figures in a row

• ncols (int) – number of figures in a column

• sharex (int) – 1 to share the x-axis between the figures

• sharey (int) – 1 to share the y-axis between the figures

• tab_title (str) – Set the title of the tab-selector

static plot_3by1(fig_axes: tuple, x: ndarray, y: ndarray, z1: ndarray, z2: ndarray, z3: ndarray, xl: str = 'x', yl: str = 'y', t1: str = 'z1', t2: str = 'z2', t3: str = 'z3') → None

Plot three contourf plots with a shared colorbar.

Parameters:

• fig_axes (tuple) – Provide the tuple (fig, axs)

• x (np.ndarray) – x mesh, e.g. P

• y (np.ndarray) – y mesh, e.g. V2

• z1 (np.ndarray) – z for subplot 1, e.g. phi

• z2 (np.ndarray) – z for subplot 2, e.g. tau1

• z3 (np.ndarray) – z for subplot 3, e.g. tau2

• t1 (str) – title for plot 1

• t2 (str) – title for plot 2

• t3 (str) – title for plot 3

• xl (str) – x label

• yl (str) – y label

plot_modulation(x: ndarray, y: ndarray, z1: ndarray, z2: ndarray, z3: ndarray, title: str = '', mask1: ndarray | None = None, mask2: ndarray | None = None, mask3: ndarray | None = None, maskZVS: ndarray | None = None, Vnum: float = 2, tab_title: str = 'add Plot title') → None

Plot three contourf plots with a shared colorbar.

Parameters:

• x (np.ndarray) – x mesh, e.g. P

• y (np.ndarray) – y mesh, e.g. V2

• z1 (np.ndarray) – z for subplot 1, e.g. phi

• z2 (np.ndarray) – z for subplot 2, e.g. tau1

• z3 (np.ndarray) – z for subplot 3, e.g. tau2

• mask1 (np.ndarray) – optional mask contour line

• mask2 (np.ndarray) – optional mask contour line

• mask3 (np.ndarray) – optional mask contour line

• Vnum (int) – Voltage number of y-axis {1, 2}

• tab_title (str) – Set the title of the tab-selector

• maskZVS (np.ndarray) – mask for ZVS

• title (str) – title of plot

plot_modulation_classic(fig_axes: tuple, x: ndarray, y: ndarray, z1: ndarray, z2: ndarray, z3: ndarray, title: str = '', mask1: ndarray | None = None, mask2: ndarray | None = None, mask3: ndarray | None = None, maskZVS: ndarray | None = None) → None

Plot three contourf plots with a shared colorbar.

Parameters:

• fig_axes (tuple) – Provide the tuple (fig, axs)

• x (np.ndarray) – x mesh, e.g. P

• y (np.ndarray) – y mesh, e.g. V2

• z1 (np.ndarray) – z for subplot 1, e.g. phi

• z2 (np.ndarray) – z for subplot 2, e.g. tau1

• z3 (np.ndarray) – z for subplot 3, e.g. tau2

• mask1 (np.ndarray) – optional mask contour line

• mask2 (np.ndarray) – optional mask contour line

• mask3 (np.ndarray) – optional mask contour line

• title (str) – title of plot

• maskZVS (np.ndarray) – mask for ZVS

plot_rms_current(mesh_V2: ndarray, mesh_P: ndarray, mvvp_iLs: ndarray) → Figure

Plot RMS currents.

Parameters:

• mesh_V2 (np.ndarray) – mesh of voltage v2 in V

• mesh_P (np.ndarray) – mesh of the power P in W

• mvvp_iLs (np.ndarray) – current i_Ls in A

pw: PlotWindow

static save_fig(fig: Figure, directory: str | None = None, name: str = '', comment: str = '', timestamp: bool = True) → None

Save the given fig as PNG and PDF.

Parameters:

• fig (matplotlib.pyplot.figure) – matplotlib figure

• directory (str) – Directory to store the figure

• name (str) – Name of the figure

• comment (str) – Comment

• timestamp (bool) – If the filename should start with a timestamp

show()

Show the plots all at once.

subplot(x: ndarray, y: ndarray, ax: Axes | None = None, xlabel: str = 'x', ylabel: str = 'y', title: str = '', xscale: str = 'linear', yscale: str = 'linear') → None

Plot a simple line plot in a subplot.

Parameters:

• x (np.ndarray)

• y (np.ndarray)

• ax (str) – axis

• xlabel (str) – x label

• ylabel (str) – y label

• title (str) – title

• xscale (str) – {“linear”, “log”, “symlog”, “logit”, …}

• yscale (str) – {“linear”, “log”, “symlog”, “logit”, …}

subplot_contourf(x: ndarray, y: ndarray, z: ndarray, mask1: ndarray | None = None, mask2: ndarray | None = None, mask3: ndarray | None = None, nan_matrix: ndarray | None = None, ax: Axes | None = None, num_cont_lines: int = 12, alpha: float = 0.75, cmap: str = 'viridis', axlinewidth: float = 0.5, axlinecolor: str = 'r', wp_x: float | None = None, wp_y: float | None = None, inlinespacing: int = -10, xlabel: str = '', ylabel: str = '', title: str = '', clabel: bool = False, markerstyle: str = 'star', z_min: float | None = None, z_max: float | None = None, square: bool = False, same_xy_ticks: bool = False) → None

Draw a subplot contourf.

The area of z where a nan can be found in nan_matrix will be shaded.

Parameters:

• x (np.ndarray) – x-coordinate

• y (np.ndarray) – y-coordinate

• z (np.ndarray) – z-coordinate

• nan_matrix (np.ndarray) – [optional] z-values where a nan is in nan_matrix will be plotted shaded

• ax (str) – choose the axis to draw this plot

• num_cont_lines (int) – [optional] number of contour lines, default to 20

• alpha (float) – [optional] shading 0…1. 1 = 100%, default to 0.5

• cmap (str) – [optional] cmap type, e.g. inferno

• axlinewidth (float) – [optional] line width of axvline and axhline, default to 0.5

• axlinecolor (str) – [optional] color of axline and star, default to red

• wp_x (float) – [optional] working point in x (for marker line or star marker)

• wp_y (float) – [optional] working point in y (for marker line or star marker)

• inlinespacing (float) – [optional] default to -10

• xlabel (str) – [optional] x-label

• ylabel (str) – [optional] y-label

• title (str) – [optional] subplot figure title

• clabel (str) – [optional] True to write labels inside the plot, default to False

• markerstyle (str) – [optional] marker style: ‘star’ or ‘line’

• z_min (float) – [optional] clip to minimum z-value

• z_max (float) – [optional] clip to maximum z-value

• mask1 (np.ndarray) – optional mask contour line

• mask2 (np.ndarray) – optional mask contour line

• mask3 (np.ndarray) – optional mask contour line

• square (bool)

• same_xy_ticks (bool)

subplot_contourf_fixedz(x: ndarray, y: ndarray, z: ndarray, mask1: ndarray | None = None, mask2: ndarray | None = None, mask3: ndarray | None = None, nan_matrix: ndarray | None = None, ax: Axes | None = None, num_cont_lines: int = 12, alpha: float = 0.75, cmap: str = 'viridis', axlinewidth: float = 0.5, axlinecolor: str = 'r', wp_x: float | None = None, wp_y: float | None = None, inlinespacing: int = -10, xlabel: str = '', ylabel: str = '', title: str = '', clabel: bool = False, markerstyle: str = 'star', z_min: float | None = None, z_max: float | None = None) → None

Draw a subplot contourf.

The area of z where a nan can be found in nan_matrix will be shaded.

Parameters:

• x (np.ndarray) – x-coordinate

• y (np.ndarray) – y-coordinate

• z (np.ndarray) – z-coordinate

• nan_matrix (np.ndarray) – [optional] z-values where a nan is in nan_matrix will be plotted shaded

• ax (str) – choose the axis to draw this plot

• num_cont_lines (int) – [optional] number of contour lines, default to 20

• alpha (float) – [optional] shading 0…1. 1 = 100%, default to 0.5

• cmap (str) – [optional] cmap type, e.g. inferno

• axlinewidth (float) – [optional] line width of axvline and axhline, default to 0.5

• axlinecolor (str) – [optional] color of axline and star, default to red

• wp_x (float) – [optional] working point in x (for marker line or star marker)

• wp_y (float) – [optional] working point in y (for marker line or star marker)

• inlinespacing (float) – [optional] default to -10

• xlabel (str) – [optional] x-label

• ylabel (str) – [optional] y-label

• title (str) – [optional] subplot figure title

• clabel (str) – [optional] True to write labels inside the plot, default to False

• markerstyle (str) – [optional] marker style: ‘star’ or ‘line’

• z_min (float) – [optional] clip to minimum z-value

• z_max (float) – [optional] clip to maximum z-value

• mask1 (np.ndarray) – optional mask contour line

• mask2 (np.ndarray) – optional mask contour line

• mask3 (np.ndarray) – optional mask contour line

subplot_contourf_nan(x: ndarray, y: ndarray, z: ndarray, nan_matrix: ndarray | None = None, ax: Axes | None = None, num_cont_lines: int = 20, alpha: float = 0.75, cmap: str = 'inferno', axlinewidth: float = 0.5, axlinecolor: str = 'r', wp_x: float | None = None, wp_y: float | None = None, inlinespacing: int = -10, xlabel: str = 'Lambda = f * L', ylabel: str = 'Turns ratio n', fontsize_axis: int = 9, fontsize_title: int = 9, title: str = '', clabel: bool = False, markerstyle: str = 'star', z_min: float | None = None, z_max: float | None = None) → None

Draw a subplot contourf.

The area of z where a nan can be found in nan_matrix will be shaded.

Parameters:

• x (np.ndarray) – x-coordinate

• y (np.ndarray) – y-coordinate

• z (np.ndarray) – z-coordinate

• nan_matrix (np.ndarray) – [optional] z-values where a nan is in nan_matrix will be plotted shaded

• ax (str) – choose the axis to draw this plot

• num_cont_lines (int) – [optional] number of contour lines, default to 20

• alpha (float) – [optional] shading 0…1. 1 = 100%, default to 0.5

• cmap (str) – [optional] cmap type, e.g. inferno

• axlinewidth (float) – [optional] line width of axvline and axhline, default to 0.5

• axlinecolor (str) – [optional] color of axline and star, default to red

• wp_x (float) – [optional] working point in x (for marker line or star marker)

• wp_y (float) – [optional] working point in y (for marker line or star marker)

• inlinespacing (float) – [optional] default to -10

• xlabel (str) – [optional] x-label

• ylabel (str) – [optional] y-label

• fontsize_axis (float) – [optional] default to 9

• fontsize_title (float) – [optional] default to 9

• title (str) – [optional] subplot figure title

• clabel (str) – [optional] True to write labels inside the plot, default to False

• markerstyle (str) – [optional] marker style: ‘star’ or ‘line’

• z_min (float) – [optional] clip to minimum z-value

• z_max (float) – [optional] clip to maximum z-value

class dct.PlotWindow(parent: None = None, window_title: str = 'plot window', figsize: tuple = (12.8, 8))

Bases: object

Class to initialize the GUI.

add_plot(title: str, figure: Figure) → None

Add plot to the GUI instance.

Parameters:

• title (str) – title for the plot

• figure (matplotlib.Figure) – Figure to add the plot

close()

Close the GUI application.

show()

Show the GUI application.

dct.Pool(processes=None, initializer=None, initargs=(), maxtasksperchild=None)

Returns a process pool object

class dct.PreSummary(*, calculation_mode: Literal['new', 'skip'], subdirectory: str)

Bases: BaseModel

Flow control for the pre-summary.

calculation_mode: Literal['new', 'skip']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

subdirectory: str

class dct.ProgressData(run_time: float, number_of_filtered_points: int, progress_status: ProgressStatus)

Bases: object

Statistic data of heat sink optimization.

number_of_filtered_points: int

progress_status: ProgressStatus

run_time: float

class dct.ProgressStatus(*values)

Bases: Enum

Enum of progress status.

Done = 2

Idle = 0

InProgress = 1

Skipped = 3

dct.Queue(maxsize=0)

Returns a queue object

class dct.QueueDetailData(circuit_data: CircuitConfigurationDataDto, inductor_list: list[ConfigurationDataEntryDto], transformer_list: list[ConfigurationDataEntryDto], heat_sink_list: list[ConfigurationDataEntryDto], summary_data: SummaryDataEntryDto, conf_process_time: float, break_point_notification: str)

Bases: object

DTO for one shared memory data exchange within a queue.

break_point_notification: str

circuit_data: CircuitConfigurationDataDto

conf_process_time: float

heat_sink_list: list[ConfigurationDataEntryDto]

inductor_list: list[ConfigurationDataEntryDto]

summary_data: SummaryDataEntryDto

transformer_list: list[ConfigurationDataEntryDto]

class dct.QueueMainData(circuit_list: list[ConfigurationDataEntryDto], inductor_main_list: list[MagneticDataEntryDto], transformer_main_list: list[MagneticDataEntryDto], heat_sink_list: list[ConfigurationDataEntryDto], summary_list: list[SummaryDataEntryDto], total_process_time: float, break_point_notification: str)

Bases: object

DTO for one shared memory data exchange within a queue.

break_point_notification: str

circuit_list: list[ConfigurationDataEntryDto]

heat_sink_list: list[ConfigurationDataEntryDto]

inductor_main_list: list[MagneticDataEntryDto]

summary_list: list[SummaryDataEntryDto]

total_process_time: float

transformer_main_list: list[MagneticDataEntryDto]

class dct.QueueParetoFrontData(pareto_front_optuna: str, evaluation_info: str, validity: bool)

Bases: object

DTO for one shared memory data exchange within a queue.

evaluation_info: str

pareto_front_optuna: str

validity: bool

class dct.RedirectResponse(url: str | URL, status_code: int = 307, headers: Mapping[str, str] | None = None, background: BackgroundTask | None = None)

Bases: Response

class dct.Request(scope: ~collections.abc.MutableMapping[str, ~typing.Any], receive: ~typing.Callable[[], ~collections.abc.Awaitable[~collections.abc.MutableMapping[str, ~typing.Any]]] = <function empty_receive>, send: ~typing.Callable[[~collections.abc.MutableMapping[str, ~typing.Any]], ~collections.abc.Awaitable[None]] = <function empty_send>)

Bases: HTTPConnection

async body() → bytes

async close() → None

form(*, max_files: int | float = 1000, max_fields: int | float = 1000, max_part_size: int = 1048576) → AwaitableOrContextManager[FormData]

async is_disconnected() → bool

async json() → Any

property method: str

property receive: Callable[[], Awaitable[MutableMapping[str, Any]]]

async send_push_promise(path: str) → None

async stream() → AsyncGenerator[bytes, None]

class dct.RequestCmd(*values)

Bases: Enum

Enum of possible commands.

continue_opt = 3

page_detail = 1

page_main = 0

pareto_front = 2

dct.RunTime

alias of RunTimeMeasurement

class dct.RunTimeMeasure(total_time: float, circuit_time_list: list[float], inductor_time_list: list[float], transformer_time_list: list[float], heat_sink_time_list: list[float], summary_time_list: list[float])

Bases: object

Statistic data of heat sink optimization.

circuit_time_list: list[float]

heat_sink_time_list: list[float]

inductor_time_list: list[float]

summary_time_list: list[float]

total_time: float

transformer_time_list: list[float]

class dct.RunTimeMeasurement

Bases: object

Runtime class for measure processing time.

continue_trigger() → None

Continue the timer without reset.

get_runtime() → float

Provide the current measured time since timer start.

Returns:

time in seconds

Return type:

float

is_timer_active() → bool

Provide the timer state.

Returns:

True, if the time is active

Return type:

bool

reset_start_trigger() → None

Reset and start the timer.

stop_trigger() → None

Stop the timer.

class dct.Sampling(sampling_method: str, sampling_points: int, v1_additional_user_point_list: list[float], v2_additional_user_point_list: list[float], p_additional_user_point_list: list[float], additional_user_weighting_point_list: list[float])

Bases: object

Sampling.

additional_user_weighting_point_list: list[float]

p_additional_user_point_list: list[float]

sampling_method: str

sampling_points: int

v1_additional_user_point_list: list[float]

v2_additional_user_point_list: list[float]

class dct.SamplingEnum(*values)

Bases: Enum

Enum for the different sampling classes.

latin_hypercube = 'latin_hypercube'

meshgrid = 'meshgrid'

dct.ServerCtl

alias of DctServer

class dct.ServerRequestData

Bases: object

Request command structure.

c_configuration_index: int

c_filtered_point_index: int

item_configuration_index: int

pareto_source: ParetoFrontSource

request_cmd: RequestCmd

class dct.SessionMiddleware(app: Callable[[MutableMapping[str, Any], Callable[[], Awaitable[MutableMapping[str, Any]]], Callable[[MutableMapping[str, Any]], Awaitable[None]]], Awaitable[None]], secret_key: str | Secret, session_cookie: str = 'session', max_age: int | None = 1209600, path: str = '/', same_site: Literal['lax', 'strict', 'none'] = 'lax', https_only: bool = False, domain: str | None = None)

Bases: object

class dct.StackedTransformerResults(**kwargs)

Bases: object

DTO contains the stacked transformer losses.

area_to_heat_sink: float

circuit_trial_file: str

p_combined_losses: ndarray

stacked_transformer_trial_number: int

volume: float

class dct.StaticFiles(*, directory: str | PathLike[str] | None = None, packages: list[str | tuple[str, str]] | None = None, html: bool = False, check_dir: bool = True, follow_symlink: bool = False)

Bases: object

async check_config() → None

Perform a one-off configuration check that StaticFiles is actually pointed at a directory, so that we can raise loud errors rather than just returning 404 responses.

file_response(full_path: str | PathLike[str], stat_result: stat_result, scope: MutableMapping[str, Any], status_code: int = 200) → Response

get_directories(directory: str | PathLike[str] | None = None, packages: list[str | tuple[str, str]] | None = None) → list[str | PathLike[str]]

Given directory and packages arguments, return a list of all the directories that should be used for serving static files from.

get_path(scope: MutableMapping[str, Any]) → str

Given the ASGI scope, return the path string to serve up, with OS specific path separators, and any ‘..’, ‘.’ components removed.

async get_response(path: str, scope: MutableMapping[str, Any]) → Response

Returns an HTTP response, given the incoming path, method and request headers.

is_not_modified(response_headers: Headers, request_headers: Headers) → bool

Given the request and response headers, return True if an HTTP “Not Modified” response could be returned instead.

lookup_path(path: str) → tuple[str, stat_result | None]

class dct.StudyData(study_name: str, optimization_directory: str)

Bases: object

Data class containing all general information to perform a study.

optimization_directory: str

study_name: str

class dct.Summary(*, calculation_mode: Literal['new', 'skip'], subdirectory: str)

Bases: BaseModel

Flow control for the summary.

calculation_mode: Literal['new', 'skip']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

subdirectory: str

class dct.SummaryDataEntryDto(configuration_name: str, number_of_combinations: int, progress_data: ProgressData)

Bases: object

DTO for queue summary information transfer.

configuration_name: str

number_of_combinations: int

progress_data: ProgressData

class dct.ThermalCalcSupport

Bases: object

Provides functions to calculate the thermal resistance.

static calculate_r_th_copper_coin(cooling_area: float, height_pcb: float = 0.00155, height_pcb_heat_sink: float = 0.003) → tuple[float, float]

Calculate the thermal resistance of the copper coin.

Assumptions are made with some geometry factors from a real copper coin for TO263 housing. :param cooling_area: cooling area in m² :type cooling_area: float :param height_pcb: PCB thickness, e.g. 1.55 mm :type height_pcb: float :param height_pcb_heat_sink: Distance from PCB to heat sink in m :type height_pcb_heat_sink: float :return: r_th_copper_coin, effective_copper_coin_cooling_area :rtype: tuple[float, float]

static calculate_r_th_tim(copper_coin_bot_area: float, transistor_cooling: TransistorCooling) → float

Calculate the thermal resistance of the thermal interface material (TIM).

Parameters:

• copper_coin_bot_area (float) – bottom copper coin area in m²

• transistor_cooling (TransistorCooling) – Transistor cooling DTO

Returns:

r_th of TIM material

Return type:

float

class dct.TomlCircuitFilterDistance(*, number_filtered_designs: int, difference_percentage: float)

Bases: BaseModel

Toml checker class for CircuitFilterDistance.

difference_percentage: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_filtered_designs: int

class dct.TomlCircuitOutputRange(*, v1_min_max_list: list[float], v2_min_max_list: list[float], p_min_max_list: list[float])

Bases: BaseModel

Definition of the DAB operating area.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

p_min_max_list: list[float]

v1_min_max_list: list[float]

v2_min_max_list: list[float]

class dct.TomlCircuitParetoDabDesign(*, design_space: TomlCircuitParetoDesignSpace, output_range: TomlCircuitOutputRange, sampling: TomlSampling, filter_distance: TomlCircuitFilterDistance)

Bases: BaseModel

Config to optimize the Dual-Active Bridge (DAB) converter.

design_space: TomlCircuitParetoDesignSpace

filter_distance: TomlCircuitFilterDistance

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_range: TomlCircuitOutputRange

sampling: TomlSampling

class dct.TomlCircuitParetoDesignSpace(*, f_s_min_max_list: list[int], l_s_min_max_list: list[float], l_1_min_max_list: list[float], l_2__min_max_list: list[float], n_min_max_list: list[float], transistor_1_name_list: list[str], transistor_2_name_list: list[str], c_par_1: float, c_par_2: float)

Bases: BaseModel

Definition of the hardware design space for electronic components.

c_par_1: float

c_par_2: float

f_s_min_max_list: list[int]

l_1_min_max_list: list[float]

l_2__min_max_list: list[float]

l_s_min_max_list: list[float]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_min_max_list: list[float]

transistor_1_name_list: list[str]

transistor_2_name_list: list[str]

class dct.TomlFilterDistance(*, factor_dc_losses_min_max_list: list[float])

Bases: BaseModel

Toml checker class for FilterDistance.

factor_dc_losses_min_max_list: list[float]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dct.TomlHeatSink(*, design_space: TomlHeatSinkDesignSpace, settings: TomlHeatSinkSettings, boundary_conditions: TomlHeatSinkBoundaryConditions, thermal_resistance_data: TomlHeatSinkThermalResistanceData)

Bases: BaseModel

Toml checker for HeatSink.

boundary_conditions: TomlHeatSinkBoundaryConditions

design_space: TomlHeatSinkDesignSpace

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

settings: TomlHeatSinkSettings

thermal_resistance_data: TomlHeatSinkThermalResistanceData

class dct.TomlHeatSinkBoundaryConditions(*, t_ambient: float, t_hs_max: float, area_min: float)

Bases: BaseModel

Toml checker for HeatSinkBoundaryConditions.

area_min: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

t_ambient: float

t_hs_max: float

class dct.TomlHeatSinkDesignSpace(*, height_c_min_max_list: list[float], width_b_min_max_list: list[float], length_l_min_max_list: list[float], height_d_min_max_list: list[float], number_fins_n_min_max_list: list[int], thickness_fin_t_min_max_list: list[float])

Bases: BaseModel

Toml checker for HeatSinkDesignSpace.

height_c_min_max_list: list[float]

height_d_min_max_list: list[float]

length_l_min_max_list: list[float]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_fins_n_min_max_list: list[int]

thickness_fin_t_min_max_list: list[float]

width_b_min_max_list: list[float]

class dct.TomlHeatSinkSettings(*, number_directions: int, factor_pcb_area_copper_coin: float, factor_bottom_area_copper_coin: float, thermal_conductivity_copper: float)

Bases: BaseModel

Toml checker for HeatSinkSettings.

factor_bottom_area_copper_coin: float

factor_pcb_area_copper_coin: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_directions: int

thermal_conductivity_copper: float

class dct.TomlHeatSinkThermalResistanceData(*, transistor_b1_cooling: list[float], transistor_b2_cooling: list[float], inductor_cooling: list[float], transformer_cooling: list[float])

Bases: BaseModel

Toml checker for HeatSinkThermalResistanceData.

inductor_cooling: list[float]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

transformer_cooling: list[float]

transistor_b1_cooling: list[float]

transistor_b2_cooling: list[float]

class dct.TomlInductor(*, design_space: TomlInductorDesignSpace, insulations: TomlInductorInsulation, boundary_conditions: TomlInductorBoundaryConditions, filter_distance: TomlFilterDistance, material_data_sources: TomlMaterialDataSources)

Bases: BaseModel

Toml checker class for Inductor.

boundary_conditions: TomlInductorBoundaryConditions

design_space: TomlInductorDesignSpace

filter_distance: TomlFilterDistance

insulations: TomlInductorInsulation

material_data_sources: TomlMaterialDataSources

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dct.TomlInductorBoundaryConditions(*, temperature: float)

Bases: BaseModel

Toml checker class for InductorBoundaryConditions.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

temperature: float

class dct.TomlInductorDesignSpace(*, core_name_list: list[str], material_name_list: list[str], litz_wire_name_list: list[str], core_inner_diameter_min_max_list: list[float], window_h_min_max_list: list[float], window_w_min_max_list: list[float])

Bases: BaseModel

Toml checker class for InductorDesignSpace.

core_inner_diameter_min_max_list: list[float]

core_name_list: list[str]

litz_wire_name_list: list[str]

material_name_list: list[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

window_h_min_max_list: list[float]

window_w_min_max_list: list[float]

class dct.TomlInductorInsulation(*, primary_to_primary: float, core_bot: float, core_top: float, core_right: float, core_left: float)

Bases: BaseModel

Toml checker class for InductorInsulation.

core_bot: float

core_left: float

core_right: float

core_top: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

primary_to_primary: float

class dct.TomlMaterialDataSources(*, permeability_datasource: str, permeability_datatype: str, permeability_measurement_setup: str, permittivity_datasource: str, permittivity_datatype: str, permittivity_measurement_setup: str)

Bases: BaseModel

Toml checker class for MaterialDataSources.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

permeability_datasource: str

permeability_datatype: str

permeability_measurement_setup: str

permittivity_datasource: str

permittivity_datatype: str

permittivity_measurement_setup: str

class dct.TomlSampling(*, sampling_method: SamplingEnum, sampling_points: int, sampling_random_seed: int | Literal['random'], v1_additional_user_point_list: list[float], v2_additional_user_point_list: list[float], p_additional_user_point_list: list[float], additional_user_weighting_point_list: list[float])

Bases: BaseModel

Definition of the sampling method.

additional_user_weighting_point_list: list[float]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

p_additional_user_point_list: list[float]

sampling_method: SamplingEnum

sampling_points: int

sampling_random_seed: int | Literal['random']

v1_additional_user_point_list: list[float]

v2_additional_user_point_list: list[float]

class dct.TomlTransformer(*, design_space: TomlTransformerDesignSpace, insulation: TomlTransformerInsulation, boundary_conditions: TomlTransformerBoundaryConditions, filter_distance: TomlTransformerFilterDistance, settings: TomlTransformerSettings)

Bases: BaseModel

Toml checker class for Transformer.

boundary_conditions: TomlTransformerBoundaryConditions

design_space: TomlTransformerDesignSpace

filter_distance: TomlTransformerFilterDistance

insulation: TomlTransformerInsulation

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

settings: TomlTransformerSettings

class dct.TomlTransformerBoundaryConditions(*, max_transformer_total_height: float, max_core_volume: float, temperature: float)

Bases: BaseModel

Toml checker class for TransformerBoundaryConditions.

max_core_volume: float

max_transformer_total_height: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

temperature: float

class dct.TomlTransformerDesignSpace(*, material_name_list: list[str], core_name_list: list[str], core_inner_diameter_min_max_list: list[float], window_w_min_max_list: list[float], window_h_bot_min_max_list: list[float], primary_litz_wire_list: list[str], secondary_litz_wire_list: list[str], n_p_top_min_max_list: list[int], n_p_bot_min_max_list: list[int])

Bases: BaseModel

Toml checker class for TransformerDesignSpace.

core_inner_diameter_min_max_list: list[float]

core_name_list: list[str]

material_name_list: list[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_p_bot_min_max_list: list[int]

n_p_top_min_max_list: list[int]

primary_litz_wire_list: list[str]

secondary_litz_wire_list: list[str]

window_h_bot_min_max_list: list[float]

window_w_min_max_list: list[float]

class dct.TomlTransformerFilterDistance(*, factor_dc_losses_min_max_list: list[float])

Bases: BaseModel

Toml checker class for TransformerFilterDistance.

factor_dc_losses_min_max_list: list[float]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dct.TomlTransformerInsulation(*, iso_window_top_core_top: float, iso_window_top_core_bot: float, iso_window_top_core_left: float, iso_window_top_core_right: float, iso_window_bot_core_top: float, iso_window_bot_core_bot: float, iso_window_bot_core_left: float, iso_window_bot_core_right: float, iso_primary_to_primary: float, iso_secondary_to_secondary: float, iso_primary_to_secondary: float)

Bases: BaseModel

Toml checker class for TransformerInsulation.

iso_primary_to_primary: float

iso_primary_to_secondary: float

iso_secondary_to_secondary: float

iso_window_bot_core_bot: float

iso_window_bot_core_left: float

iso_window_bot_core_right: float

iso_window_bot_core_top: float

iso_window_top_core_bot: float

iso_window_top_core_left: float

iso_window_top_core_right: float

iso_window_top_core_top: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dct.TomlTransformerSettings(*, fft_filter_value_factor: float, mesh_accuracy: float)

Bases: BaseModel

Toml checker class for TransformerSettings.

fft_filter_value_factor: float

mesh_accuracy: float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class dct.Transformer(*, number_of_trials: int, calculation_mode: Literal['new', 'continue', 'skip'], subdirectory: str)

Bases: BaseModel

Flow control for the transformer.

calculation_mode: Literal['new', 'continue', 'skip']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_of_trials: int

subdirectory: str

class dct.TransformerOptimization

Bases: object

Optimization of the transformer.

fem_simulation_handler(filter_data: FilterData, factor_dc_losses_min_max_list: list[float] | None, debug: Debug) → None

Control the multi simulation processes.

Parameters:

• filter_data (dct.FilterData) – Information about the filtered designs

• factor_dc_losses_min_max_list (float) – Filter factor for min and max losses to use filter the results

• debug (dct.Debug) – Debug DTO

get_number_of_performed_calculations() → int

Provide the number of performed calculations.

Returns:

int: Number of performed calculations

Return type:

int

get_progress_data(filtered_list_id: int) → ProgressData

Provide the progress data of the optimization.

Parameters:

filtered_list_id (int) – List index of the filtered operation point from circuit

Returns:

Progress data: Processing start time, actual processing time, number of filtered transformer Pareto front points and status.

Return type:

ProgressData

initialize_transformer_optimization_list(toml_transformer: TomlTransformer, study_data: StudyData, filter_data: FilterData) → bool

Initialize the configuration.

Parameters:

• toml_transformer (dct.TomlTransformer) – transformer toml file

• study_data (dct.StudyData) – Study data

• filter_data (dct.FilterData) – Information about the filtered circuit designs

Returns:

True, if the configuration was successful initialized

Return type:

bool

optimization_handler_reluctance_model(filter_data: FilterData, target_number_trials: int, factor_dc_losses_min_max_list: list[float] | None, debug: Debug) → None

Control the multi simulation processes.

:param filter_data : Information about the filtered circuit designs :type filter_data : dct.FilterData :param target_number_trials: Number of trials for the optimization :type target_number_trials: int :param factor_dc_losses_min_max_list: Filter factor for the offset, related to the minimum/maximum DC losses :type factor_dc_losses_min_max_list: float :param debug: Debug DTO :type debug: dct.Debug

static verify_optimization_parameter(toml_transformer: TomlTransformer) → tuple[bool, str]

Verify the input parameter ranges.

Parameters:

toml_transformer (dct.TomlInductor) – toml inductor configuration

Returns:

True, if the configuration was consistent

Return type:

bool

class dct.TransformerOptimizationDto(circuit_filtered_point_filename: str, progress_data: ProgressData, transformer_optimization_dto: StoSingleInputConfig)

Bases: object

DTO for the transformer optimization.

circuit_filtered_point_filename: str

progress_data: ProgressData

transformer_optimization_dto: StoSingleInputConfig

class dct.TransformerTargetParameters(l_s12_target: float, l_h_target: float, n_target: float, time_current_1_vec: ndarray, time_current_2_vec: ndarray, temperature: float)

Bases: object

Target transformer parameters for the optimization.

l_h_target: float

l_s12_target: float

n_target: float

temperature: float

time_current_1_vec: ndarray

time_current_2_vec: ndarray

class dct.TransistorCooling(tim_conductivity: float, tim_thickness: float)

Bases: object

Fix parameters for the transistor cooling.

tim_conductivity: float

tim_thickness: float

class dct.TransistorDTO(name: str, t_j_max_op: ndarray, c_oss: ndarray, q_oss: ndarray, housing_area: float64, cooling_area: float64, r_th_jc: ndarray, r_channel: ndarray)

Bases: object

Contains constant transistor information.

c_oss: ndarray

cooling_area: float64

housing_area: float64

name: str

q_oss: ndarray

r_channel: ndarray

r_th_jc: ndarray

t_j_max_op: ndarray

dct.abspath(path)

Return an absolute path.

dct.c_flag

alias of CheckCondition

dct.calc_hf_currents(angles_sorted: ndarray, i_l_s_sorted: ndarray, i_l_1_sorted: ndarray, i_l_2_sorted: ndarray, n: float64) → tuple

Calculate i_hf_1_rms and i_hf_2_rms from i_l_s, i_l_1 and i_l_2.

Parameters:

• angles_sorted (np.ndarray) – sorted angles

• i_l_s_sorted (np.ndarray) – sorted currents i_l_s

• i_l_1_sorted (np.ndarray) – sorted currents i_l_1

• i_l_2_sorted (np.ndarray) – sorted currents i_l_2

• n (np.ndarray) – transfer ratio

Returns:

(i_hf_1_rms, i_hf_2_rms, i_hf_1_sorted, i_hf_2_sorted)

Return type:

tuple

dct.calc_modulation_params(n: float64, ls: float64, lc1: float64, lc2: float64, fs: ndarray | int | float, c_oss_1: ndarray, c_oss_2: ndarray, v1: ndarray, v2: ndarray, power: ndarray) → dict

OptZVS (Optimal ZVS) Modulation calculation, which will return phi, tau1 and tau2.

Parameters:

• n (float) – Transformer turns ratio n1/n2.

• ls (float) – DAB converter series inductance. (Must not be zero!)

• lc1 (float) – Side 1 commutation inductance. Use np.inf it not present.

• lc2 (float) – Side 2 commutation inductance. Use np.inf it not present. (Must not be zero!)

• fs (float) – Switching frequency, can be a fixed value or a meshgrid with same shape as the other meshes.

• c_oss_1 (np.array) – Side 1 MOSFET Coss(Vds) curve from Vds=0V to >= V1_max. Just one row with Coss data and index = Vds.

• c_oss_2 (np.array) – Side 2 MOSFET Coss(Vds) curve from Vds=0V to >= V2_max. Just one row with Coss data and index = Vds.

• v1 (np.array) – Input voltage meshgrid (voltage on side 1).

• v2 (np.array) – Output voltage meshgrid (voltage on side 2).

• power (np.array) – DAB input power meshgrid (P=V1*I1).

Returns:

dict with phi, tau1, tau2, masks (phi has First-Falling-Edge alignment!)

dct.calc_rms(alpha_rad: ndarray, beta_rad: ndarray, gamma_rad: ndarray, delta_rad: ndarray, i_alpha: ndarray, i_beta: ndarray, i_gamma: ndarray, i_delta: ndarray) → tuple[object, ndarray, ndarray]

Calculate a single RMS current for some single points, with a linear current between them.

Angles alpha to delta according to “closed-form solution for efficient ZVS modulation of DAB converters”. Function works with multidimensional arrays.

Interval is symmetric by pi. Starts from zero, ends with pi. Some angles will be higher than pi, needs to be mirrored to values smaller than pi.

Everything must be numpy!

Parameters:

• alpha_rad (np.ndarray) – angle alpha in rad

• beta_rad (np.ndarray) – angle beta in rad

• gamma_rad (np.ndarray) – angle gamma in rad

• delta_rad (np.ndarray) – angle delta in rad

• i_alpha (np.ndarray) – current at angle alpha

• i_beta (np.ndarray) – current at angle beta

• i_gamma (np.ndarray) – current at angle gamma

• i_delta (np.ndarray) – current at angle delta

Returns:

rms current

dct.calc_rms_currents(config: CircuitConfig, calc_from_config: CalcFromCircuitConfig, calc_modulation: CalcModulation) → tuple

Calculate the RMS currents in l_s, l_1 and l_2 for the given input values.

Works with 2- and 3-dimensional input arrays (2D e.g. v_2 and power, 3D e.g. v_1, v_2 and power) everything must be numpy!

Parameters:

• config – design configuration DTO

• calc_from_config – Additional input parameters calculated once from the input configuration

• calc_modulation – Calculated modulation parameters DTO

Returns:

i_l_s_rms, i_l_1_rms, i_l_2_rms, angles_sorted, i_l_s_sorted, i_l_1_sorted, i_l_2_sorted, angles_unsorted

Return type:

tuple

dct.calc_transistor_rms_currents(i_hf_rms: float) → float

Calculate the transistor RMS currents from the i_HF currents (bridge 1 or bridge 2).

Parameters:

i_hf_rms (float) – bridge 1 or bridge 2 RMS current

Returns:

bridge 1 or bridge 2 transistor RMS current

Return type:

float

dct.calculate_r_th_copper_coin(cooling_area: float, height_pcb: float = 0.00155, height_pcb_heat_sink: float = 0.003) → tuple[float, float]

Calculate the thermal resistance of the copper coin.

Assumptions are made with some geometry factors from a real copper coin for TO263 housing. :param cooling_area: cooling area in m² :type cooling_area: float :param height_pcb: PCB thickness, e.g. 1.55 mm :type height_pcb: float :param height_pcb_heat_sink: Distance from PCB to heat sink in m :type height_pcb_heat_sink: float :return: r_th_copper_coin, effective_copper_coin_cooling_area :rtype: tuple[float, float]

dct.calculate_r_th_tim(copper_coin_bot_area: float, transistor_cooling: TransistorCooling) → float

Calculate the thermal resistance of the thermal interface material (TIM).

Parameters:

• copper_coin_bot_area (float) – bottom copper coin area in m²

• transistor_cooling (TransistorCooling) – Transistor cooling DTO

Returns:

r_th of TIM material

Return type:

float

dct.check_for_missing_toml_files(working_directory: str) → None

Check for missing toml default files. Generate them, if missing.

Parameters:

working_directory (str) – working directory

dct.check_user_points_in_min_max_region(dim_min_max_list: list[float], dim_points_list: list[float]) → None

Check if given operating point is within the limits of the operating area.

Parameters:

• dim_min_max_list (list[float]) – e.g. [175, 295]

• dim_points_list (list[float]) – list of user-given operating points, e.g. [200, 230]

Raises:

ValueError – in case of list is out of min/max limits

dct.colors() → dict

Colors according to the GNOME color scheme (Color 4).

dct.cpu_count()

Returns the number of CPUs in the system

dct.current_process()

Return process object representing the current process

dct.full_angle_waveform_from_angles(sorted_angles: ndarray) → ndarray

Generate the full 2pi-periodic angle waveform from the four sorted angles [alpha, beta, gamma, delta].

Parameters:

sorted_angles (np.ndarray) – [alpha, beta, gamma, delta], but in sorted order

Returns:

2pi-periodic angles for a full waveform

Return type:

np.ndarray

dct.full_current_waveform_from_currents(sorted_currents: ndarray) → ndarray

Generate the full 2pi-periodic current waveform from the four current values [i_alpha, i_beta, i_gamma, i_delta].

Parameters:

sorted_currents (np.ndarray) – [i_alpha, i_beta, i_gamma, i_delta], but sorted

Returns:

2pi-periodic current waveform

Return type:

np.ndarray

dct.full_waveforms_from_angles_currents(angles_rad_sorted: ndarray, *sorted_currents: ndarray) → tuple[ndarray]

Generate the full 2pi-periodic time and current waveform from the four time and current values at [alpha, beta, gamma, delta].

Multiple current inputs possible. Sorts out same time values, e.g [0, 2, 3.14, 3,14] -> [0, 2, 3.14]

Parameters:

• angles_rad_sorted (np.ndarray) – [alpha, beta, gamma, delta], but in sorted order. Unit is radiant.

• sorted_currents (np.ndarray) – [i_alpha, i_beta, i_gamma, i_delta], but sorted

Returns:

2pi-periodic time and current waveforms

Return type:

np.ndarray

dct.generate_circuit_toml(working_directory: str) → None

Generate the default DabCircuitConf.toml file.

Parameters:

working_directory (str) – working directory

dct.generate_flow_control_toml(working_directory: str) → None

Generate the default progFlow.toml file.

Parameters:

working_directory (str) – working directory

dct.generate_heat_sink_toml(working_directory: str) → None

Generate the default DabHeatSinkConf.toml file.

Parameters:

working_directory (str) – working directory

dct.generate_inductor_toml(working_directory: str) → None

Generate the default DabInductorConf.toml file.

Parameters:

working_directory (str) – working directory

dct.generate_logging_config(working_directory: str) → None

Generate the default logging configuration file.

Parameters:

working_directory (str) – working directory

dct.generate_transformer_toml(working_directory: str) → None

Generate the default DabTransformerConf.toml file.

Parameters:

working_directory (str) – working directory

dct.get_free_port(start: int = 43047, stop: int = 50000) → int

Get a random free port in Range start <= port < stop.

Parameters:

• start (int) – start port

• stop (int) – stop port

Returns:

dct.global_plot_settings_font_latex() → None

Set the plot fonts to LaTeX-font.

dct.global_plot_settings_font_sansserif() → None

Set the plot fonts to Sans-Serif-Font.

dct.latin_hypercube(dim_1_min: float, dim_1_max: float, dim_2_min: float, dim_2_max: float, dim_3_min: float, dim_3_max: float, total_number_points: int, dim_1_user_given_points_list: list[float], dim_2_user_given_points_list: list[float], dim_3_user_given_points_list: list[float], sampling_random_seed: int | None) → tuple[ndarray, ndarray, ndarray]

Latin hypercube sampling for a given 3-dimensional user input.

Parameters:

• dim_1_min – dimension 1 minimum, e.g. 690

• dim_1_max – dimension 1 maximum, e.g. 710

• dim_2_min – dimension 2 minimum, e.g. 175

• dim_2_max – dimension 2 maximum, e.g. 295

• dim_3_min – dimension 3 minimum, e.g. -2000

• dim_3_max – dimension 3 maximum, e.g. 2000

• total_number_points – point to sample by the sampler

• dim_1_user_given_points_list – user-given points for dimension 1, e.g. [695, 705]

• dim_2_user_given_points_list – user-given points for dimension 2, e.g. [289, 299]

• dim_3_user_given_points_list – user-given points for dimension 3, e.g. [-1300, 1530]

• sampling_random_seed (int) – random seed for the hypercube sampling (reproducible)

Returns:

dim_1_all_points, dim_2_all_points, dim_3_all_points

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

dct.plot_calc_i_hf_waveforms(dab_dto: CircuitDabDTO, compare_gecko_waveforms: bool = False) → None

Plot calculated current waveforms for i_hf_1 and i_hf_2.

Parameters:

• dab_dto (CircuitDabDTO) – DAB DTO

• compare_gecko_waveforms (bool) – True to compare calculation with simulated waveforms (GeckoCIRCUITS)

dct.plot_calc_waveforms(dab_dto: CircuitDabDTO, compare_gecko_waveforms: bool = False) → None

Plot calculated current waveforms for Ls, Lc1, Lc2.

Parameters:

• dab_dto (CircuitDabDTO) – DAB DTO

• compare_gecko_waveforms (bool) – True to compare calculation with simulated waveforms (GeckoCIRCUITS)

dct.plot_calculation_results(dab_config: CircuitDabDTO) → None

Calculate the DAB operating points and show the results.

Parameters:

dab_config (CircuitDabDTO) – DAB configuration file

dct.plot_gecko_simulation_results(dab_config: CircuitDabDTO, simulation_name: str, comment: str, directory: str, show_plot: bool = True) → None

Plot the results from the GeckoCIRCUITS simulation.

Parameters:

• dab_config (CircuitDabDTO) – Dual-Active-Bridge (DAB) configuration file

• simulation_name (str) – Simulation name

• comment (str) – Comment for the simulation, appears in the logs.

• directory (str) – Directory to plot

• show_plot (bool) – True (default) to show the plots.

dct.plot_mode_overview(dab_config: CircuitDabDTO) → None

Mode overview of the converter. This function is for debugging.

Parameters:

dab_config (dct.CircuitDabDTO) – DAB configuration file

dct.plot_modulation(x: ndarray, y: ndarray, z1: ndarray, z2: ndarray, z3: ndarray, title: str = '', mask1: ndarray | None = None, mask2: ndarray | None = None, mask3: ndarray | None = None, maskZVS: ndarray | None = None, Vnum: int = 2, filename: str = 'Plot_title', latex: bool = False) → None

Plot three contourf plots with a shared colorbar.

Parameters:

• x (np.ndarray) – x mesh, e.g. P

• y (np.ndarray) – y mesh, e.g. V2

• z1 (np.ndarray) – z for subplot 1, e.g. phi

• z2 (np.ndarray) – z for subplot 2, e.g. tau1

• z3 (np.ndarray) – z for subplot 3, e.g. tau2

• mask1 (np.ndarray) – optional mask contour line

• mask2 (np.ndarray) – optional mask contour line

• mask3 (np.ndarray) – optional mask contour line

• Vnum (int) – Voltage number of y-axis {1, 2}

• maskZVS (np.ndarray) – ZVS mask

• Vnum

• filename (str) – name of the file

• latex (bool) – True to set font to LaTeX font

• title (str) – title of the plot

dct.plot_rms_current(mesh_v2: ndarray, mesh_p: ndarray, mvvp_i_ls: ndarray) → Figure

Plot the RMS currents.

Parameters:

• mesh_v2 (np.ndarray) – mesh of voltage v2 in V

• mesh_p (np.ndarray) – mesh of the power P in W

• mvvp_i_ls (np.ndarray) – current i_Ls in A

dct.plot_samples(dim_1_min_max_list: list[float], dim_2_min_max_list: list[float], dim_3_min_max_list: list[float], number_user_points: int, dim_1_points_list: list[float], dim_2_points_list: list[float], dim_3_points_list: list[float]) → None

Plot sampling in a 3D-room.

Parameters:

• dim_1_min_max_list (list[float]) – dimension 1 as min-max-list, e.g. [690, 710]

• dim_2_min_max_list (list[float]) – dimension 2 as min-max-list, e.g. [175, 295]

• dim_3_min_max_list (list[float]) – dimension 3 as min-max-list, e.g. [-2000, 2000]

• number_user_points (int) – Number of user given points (color change)#

• dim_1_points_list (list[float]) – sampled points in dimension 1 (e.g. by latin hypercube)

• dim_2_points_list (list[float]) – sampled points in dimension 2 (e.g. by latin hypercube)

• dim_3_points_list (list[float]) – sampled points in dimension 3 (e.g. by latin hypercube)

dct.show_plot()

Show the plots all at once.

dct.start_gecko_simulation(mesh_v1: ndarray, mesh_v2: ndarray, mesh_p: ndarray, mod_phi: ndarray, mod_tau1: ndarray, mod_tau2: ndarray, t_dead1: float | ndarray, t_dead2: float | ndarray, fs: int | ndarray | float64, ls: float, lc1: float, lc2: float, n: float, t_j_1: float, t_j_2: float, simfilepath: str, timestep: float, number_sim_periods: int, transistor_1_name: str, transistor_2_name: str, lossfilepath: str, i_ls_start: ndarray, i_lc1_start: ndarray, i_lc2_start: ndarray, timestep_pre: float = 0, number_pre_sim_periods: int = 0, geckoport: int = 43036, c_par_1: float | None = None, c_par_2: float | None = None, get_waveforms: bool = False) → tuple[dict, defaultdict]

Start the GeckoCIRCUITS simulation.

Parameters:

• mesh_v1 (np.array) – mesh of voltage v1 in V

• mesh_v2 (np.array) – mesh of voltage v2 in V

• mesh_p (np.array) – mesh of the power P in W

• mod_phi (np.array) – matrix with modulation parameter phi

• mod_tau1 (np.array) – matrix with modulation parameter tau_1

• mod_tau2 (np.array) – matrix with modulation parameter tau_2

• t_dead1 (float) – dead time for bridge 1 in seconds

• t_dead2 (float) – dead time for bridge 2 in seconds

• fs (float) – switching frequency in Hz

• ls (float) – series inductance in H

• lc1 (float) – Commutation inductance for bridge 1 in H

• lc2 (float) – Commutation inductance for bridge 2 in H

• n (float) – transfer ratio

• t_j_1 (float) – MOSFET junction temperature for bridge 1 in degree Celsius

• t_j_2 (float) – MOSFET junction temperature for bridge 2 in degree Celsius

• simfilepath (float) – simulation file filepath

• timestep (float) – timestep in seconds, e.g. 5e-9

• number_sim_periods (int) – simulation periods

• timestep_pre (float) – time-steps of pre-simulation, e.g. 50e-9

• number_pre_sim_periods (int) – pre-simulation periods (not recorded)

• geckoport (int) – port of GeckoCIRCUITS to connect

• c_par_1 (float) – parasitic capacitance for one single MOSFET of bridge 1

• c_par_2 (float) – parasitic capacitance for one single MOSFET of bridge 2

• get_waveforms (bool) – True to return i_Ls, i_Lc1 and i_Lc2. Defaults to False.

• lossfilepath (str) – file path of loss files for transistors

• transistor_1_name (str) – Name of transistor 1

• transistor_2_name (str) – Name of transistor 2

• i_ls_start (np.array) – start current of L_s in A

• i_lc1_start (np.array) – start current of L_c1 in A

• i_lc2_start (np.array) – start current of the L_c2 in A (on secondary side)

dct.timeit(func)

Measure execution time of a function by the use of a decorator.

Use this in front of a function to measure execution time @timeit

Parameters:

func (python function) – function to stop the time

dct.transistor_conduction_loss(transistor_rms_current: float, transistor_dto: TransistorDTO) → ndarray

Calculate the transistor conduction losses.

Parameters:

• transistor_rms_current (float) – transistor RMS current in A

• transistor_dto (dct.TransistorDTO) – transistor DTO (Data transfer object)

Returns:

transistor conduction loss in W

Return type:

float

dct.version(distribution_name)

Get the version string for the named package.

Parameters:

distribution_name – The name of the distribution package to query.

Returns:

The version string for the package as defined in the package’s “Version” metadata key.