组件向导

导航

• 索引
• 模块 |
• 下一页 |
• 上一页 |

组件向导

classmhi.pscad.automation.wizard.``UserDefnWizard(name : str)

用户定义构建向导

用法：

wizard = UserDefnWizard(“definition_name”)
wizard.description = “一个乘法增益因子组件”
wizard.port.input(-2, 0, “In”, Signal.REAL)
wizard.port.output(2, 0, “Out”, Signal.REAL)
config = wizard.category.add(“Configuration”)
config.real(‘Gain’, description=“增益因子”)
wizard.graphics.text(“Gain”, 0, 4)
wizard.script[‘Fortran’] = " $Out = $In * $Gain"

defn = wizard.create_definition(project)

canvas.create_component(defn, x, y)

2.2 版本新增。

name

定义名称（提示）

创建定义时，PSCAD 可能会更改定义名称以确保其唯一性。

description

组件定义描述

propertyport

端口容器。

使用

• wizard.port.input(X, Y, "port_name", ...),
• wizard.port.output(X, Y, "port_name", ...),
• wizard.port.electrical(X, Y, "port_name", ...),

来添加新的输入、输出和电气连接端口。

使用 wizard.port["name"] 通过名称访问一个 Port。

由于同一端口名称可能因不同的 enable 条件而存在多次，请使用 for port in wizard.port: 来遍历所有已定义的端口。

propertygraphics

图形容器。

可以使用 for shape in wizard.graphics: 遍历当前定义的图形形状（不包括端口线和箭头）。

使用

• wizard.graphics.text(...),
• wizard.graphics.line(...),
• wizard.graphics.arrow(...),
• wizard.graphics.rectangle(...),

来添加新的文本、线条、箭头和矩形。

注意

端口线和箭头将自动创建。

form_caption

参数表单标题

form_width

参数表单宽度

form_height

参数表单高度

form_splitter

参数表单默认分隔器位置

form_category_width

参数表单类别树宽度

form_help_width

参数表单动态帮助面板宽度

propertycategory

组件参数表单类别容器

使用 wizard.category.add("category_name", ...) 向表单添加类别。然后可以将参数添加到该类别对象。

使用 wizard.category["name"] 通过名称访问一个 category。

propertyparameter

组件参数容器

使用 wizard.parameter["name"] 访问现有参数。

注意

参数只能添加到类别对象。使用 wizard.category.add(...) 创建类别，然后将参数添加到该类别对象。

propertyscript

组件脚本容器

使用 wizard.script['Fortran'] = '''...''' 设置脚本部分。

有效的部分有：Branch, Checks, Computations, Dsdyn, Dsout, Fortran, MANA, Matrix-Fill, Model-Data, T-Lines, Transformers Help, FlyBy, 和 Comments。

create_definition(prj : Project) → Definition

在给定项目中创建定义。

一旦将所需的端口、图形以及表单参数和类别添加到向导后，此方法将在给定项目中创建所需的组件定义，然后可以使用该定义来创建组件的实例。

注意

向导中配置的定义名称仅是一个提示。当 PSCAD 创建定义时，可能会更改定义名称，因此请参考返回的定义以获取实际的定义名称。

端口

classmhi.pscad.automation.wizard.UserDefnWizard.``Ports

端口容器，通过 wizard.port 属性访问。

使用 wizard.port["name"] 通过名称访问一个 Port。

由于同一端口名称可能因不同的 enable 条件而存在多次，请使用 for port in wizard.port: 来遍历所有已定义的端口。

electrical(x : int, y : int, name : str, electrical_type : Union[str, mhi.pscad.automation.types.Electrical] = ‘FIXED’, dim : int = 1, enable : str = ‘true’, internal : bool = False)

创建一个新的电气连接端口

input(x : int, y : int, name : str, data_type : Union[str, mhi.pscad.automation.types.Signal], dim : int = 1, enable : str = ‘true’, arrow : Union[bool, Tuple[int, int]] = True)

创建一个新的控制信号输入端口

output(x : int, y : int, name : str, data_type : Union[str, mhi.pscad.automation.types.Signal], dim : int = 1, enable : str = ‘true’, arrow : Union[bool, Tuple[int, int]] = False)

创建一个新的控制信号输出端口

Port

classmhi.pscad.automation.wizard.UserDefnWizard.``Port

组件输入/输出/电气连接

data_type

I/O 端口数据类型 (BOOLEAN, INTEGER, REAL, COMPLEX)

dim

端口维度。

维度为 1 表示标量线连接。维度大于 1 表示数组线连接。维度为 0 则继承所连接线的维度。

electrical_type

电气端口类型 (FIXED, SWITCHED, REMOVABLE)

enable

端口启用条件

internal

用于创建无外部连接的电气节点

mode

端口节点类型 (ELECTRICAL, INPUT, OUTPUT)

name

端口名称

propertyside

端口标签位置 (NONE, LEFT, ABOVE, BELOW, RIGHT, AUTO)

x

端口 X 坐标

y

端口 Y 坐标

图形

classmhi.pscad.automation.wizard.UserDefnWizard.``Graphics

图形元素容器，通过 wizard.graphics 属性访问。

可以使用 for shape in wizard.graphics: 遍历当前定义的图形形状（不包括端口线和箭头）。

arrow(x1: int , y1: int , x2: int , y2: int , length: int = 5 , width: int = 5 , * , enable: str = ‘true’ , color: str = ‘black’ , line_style: Union[str , mhi.pscad.automation.types.LineStyle] = <LineStyle.SOLID: 0>, thickness: int = 0 , port: str = ‘’)

从 [x1,y1] 到 [x2,y2] 创建一个箭头。

line(x1: int , y1: int , x2: int , y2: int , * , enable: str = ‘true’ , color: str = ‘black’ , line_style: Union[str , mhi.pscad.automation.types.LineStyle] = <LineStyle.SOLID: 0>, thickness: int = 0 , port: str = ‘’)

在 [x1,y1] 和 [x2,y2] 之间创建一条线。

rectangle(x1: int , y1: int , x2: int , y2: int , enable: str = ‘true’ , color: str = ‘black’ , line_style: Union[str , mhi.pscad.automation.types.LineStyle] = <LineStyle.SOLID: 0>, thickness: int = 0 , port: str = ‘’ , foreground: str = ‘Black’ , background: str = ‘White’ , fill_style: int = 0)

在角点 [x1,y1] 和 [x2,y2] 之间创建一个矩形。

text(text: str , x: int = 0 , y: int = 5 , * , color: str = ‘Black’ , enable: str = ‘true’ , angle: int = 0 , anchor: Union[str , mhi.pscad.automation.types.Align] = <Align.CENTER: 1>, full_font: str = 'Tahoma , 12world’)

创建一个文本标签。

Text

classmhi.pscad.automation.wizard.UserDefnWizard.``Text

一个文本标签

anchor

文本锚点 (LEFT, CENTER, RIGHT)

angle

文本角度（度）

color

颜色

enable

文本可见性条件

full_font

文本字体

text

文本标签

x

X 坐标

y

Y 坐标

Line

classmhi.pscad.automation.wizard.UserDefnWizard.``Line

一条直线

color

颜色

enable

可见性条件

line_style

线型 (SOLID, DOT, DASH, DOTDASH)

port

关联的端口名称（用于线宽）

thickness

线宽

0	0.2pt
1	0.4pt
2	0.6pt
3	0.8pt
4	1.0pt
5	1.2pt
6	1.4pt
7	关联端口

x

X 坐标

y

Y 坐标

Rectangle

classmhi.pscad.automation.wizard.UserDefnWizard.``Rectangle

一个轴对齐的矩形。

background

背景填充颜色

color

颜色

enable

可见性条件

fill_style

填充样式 (SOLID, HOLLOW, CROSS, HORIZONTAL, VERTICAL, )

foreground

前景填充颜色

height

高度

line_style

线型 (SOLID, DOT, DASH, DOTDASH)

port

关联的端口名称（用于线宽）

thickness

线宽

0	0.2pt
1	0.4pt
2	0.6pt
3	0.8pt
4	1.0pt
5	1.2pt
6	1.4pt
7	关联端口

width

宽度

x

X 坐标

y

Y 坐标

参数表单

classmhi.pscad.automation.wizard.UserDefnWizard.``Parameters

参数容器，通过 wizard.parameter 属性访问。

注意

参数只能添加到类别对象。使用 wizard.category.add(...) 创建类别，然后将参数添加到该类别对象。

keys() → List[str]

参数名称列表

Categories

Category

classmhi.pscad.automation.wizard.UserDefnWizard.``Category

组件参数表单类别，通过 wizard.category 属性访问。

使用 category = wizard.category.add("category_name", ...) 创建类别后，使用

• category.text("param_name", ...),
• category.logical("param_name", ...),
• category.boolean("param_name", ...),
• category.choice("param_name", ...),
• category.integer("param_name", ...),
• category.real("param_name", ...),

向该类别添加参数。

属性

Category.``name

类别名称

Category.``level

类别级别，用于缩进类别树节点

Category.``enable

类别启用条件

方法

Category.``text(name : str, * , description : str = None, group : str = ‘’, enable : str = None, visible : str = None, value : str = ‘’, help : str = None, help_mode : str = None, regex : str = None, allow_empty_strings : bool = True, minimum_length : int = None, maximum_length : int = None, error_msg : str = None)

向类别添加一个文本参数

Category.``logical(name : str, * , description : str = None, group : str = ‘’, enable : str = None, visible : str = None, value : str = ‘.TRUE.’, help : str = None, help_mode : str = None)

向类别添加一个逻辑参数

Category.``boolean(name : str, * , description : str = None, group : str = ‘’, enable : str = None, visible : str = None, true_text : str = ‘Show’, false_text : str = ‘Hide’, value : str = ‘.TRUE.’, help : str = None, help_mode : str = None)

向类别添加一个布尔参数。

默认情况下，布尔参数在真或假时显示 Show 或 Hide，但可以使用 true_text="...", false_text="..." 参数更改这些文本。

Category.``choice(name : str, * , choices : Dict[int, str], description : str = None, group : str = ‘’, enable : str = None, visible : str = None, value : str = ‘’, help : str = None, help_mode : str = None)

向类别添加一个选择参数。

必须通过向 choices={...} 参数传递一个字典来指定选项。字典键应为整数，值为每个键显示的文本。

Category.``integer(name : str, * , description : str = None, group : str = ‘’, enable : str = None, visible : str = None, value : int = 0, help : str = None, help_mode : str = None, minimum : int = - 2147483647, maximum : int = 2147483647)

向类别添加一个整数参数。

Category.``real(name : str, * , description : str = None, group : str = ‘’, enable : str = None, visible : str = None, value : float = 0.0, help : str = None, help_mode : str = None, minimum : float = - 1e+308, maximum : float = 1e+308, units : str = None)

向类别添加一个实数参数。

Parameters

classmhi.pscad.automation.wizard.UserDefnWizard.``Categories

组件参数表单类别容器，通过 wizard.category 属性访问。

add(name , * , enable : str = ‘true’, level : int = None)

添加一个新类别

keys() → List[str]

表单类别名称列表

Parameter

classmhi.pscad.automation.wizard.UserDefnWizard.``Parameter

组件参数

allow_empty_strings

文本参数是否允许为空？

propertychoices

选择参数选项

description

参数描述

enable

参数启用条件

error_message

文本参数无效输入错误消息

group

参数组

help_mode

参数帮助模式 (Overwrite 或 Append)

help_text

参数帮助文本

maximum

参数最大限制

minimum

参数最小限制

name

参数名称

regex

文本参数正则表达式过滤器

type

参数类型

units

参数单位

value

参数描述

visible

参数可见性条件

脚本

classmhi.pscad.automation.wizard.UserDefnWizard.``Scripts

脚本部分容器

items() → Iterable[Tuple[str, str]]

脚本名称/值对的生成器

keys() → List[str]

当前定义的脚本部分名称

这是一份 PSCAD 软件中“组件向导”（Component Wizard）的 Python API 文档。

简单来说，它教你如何用 Python 代码自动生成一个自定义的电力系统仿真元件，而不必在 PSCAD 的图形界面里手动画图和写 Fortran 代码。

以下是这份文档的核心内容解释，帮你快速抓住重点：

1. 这个向导是干什么的？

PSCAD 里本来可以手动创建自定义元件（图形+代码）。但这个 UserDefnWizard 让你可以用 Python 脚本自动化完成整个过程。适合以下场景：

• 需要批量生成多个类似的元件。
• 元件的参数、图形或代码需要动态生成。
• 想把元件创建过程集成到自动化仿真流程中。

2. 最简使用示例（让你秒懂流程）

文档开头的例子非常经典，创建一个简单的“乘法增益”元件：

# 1. 创建一个名为 "GainBlock" 的元件向导
wizard = UserDefnWizard("GainBlock")

# 2. 设置描述（鼠标悬停时显示）
wizard.description = "一个乘法增益因子组件"

# 3. 添加端口（输入在左边 x=-2，输出在右边 x=2）
wizard.port.input(-2, 0, "In", Signal.REAL)
wizard.port.output(2, 0, "Out", Signal.REAL)

# 4. 添加一个叫 "Configuration" 的参数类别，里面放一个实数参数 "Gain"
config = wizard.category.add("Configuration")
config.real('Gain', description="增益因子")

# 5. 在元件图形上显示这个参数的值（坐标 0,4 显示 "Gain"）
wizard.graphics.text("Gain", 0, 4)

# 6. 写 Fortran 代码（$Out 等是自动替换的参数占位符）
wizard.script['Fortran'] = "      $Out = $In * $Gain"

# 7. 在指定的项目（project）中真正创建这个元件定义
defn = wizard.create_definition(project)

# 8. 在画布上放置这个元件
canvas.create_component(defn, x, y)

3. 文档结构拆解

这份文档主要包含以下几个部分：

章节	作用	关键方法/属性
主类 UserDefnWizard	向导的核心对象，管理整个元件。	name, description, port, graphics, category, parameter, script, create_definition()
端口 Ports	定义元件的电气接口。	input(), output(), electrical()（坐标、名称、数据类型）
图形 Graphics	定义元件在画布上长什么样。	text(), line(), arrow(), rectangle()
参数表单	定义用户双击元件时弹出的设置对话框。	category.add() 添加选项卡，然后添加 real(), integer(), choice(), boolean() 等参数
脚本 Scripts	定义元件的仿真代码。	script['Fortran'] = '代码'（也支持 Branch, DSDyn 等段）

4. 一些重要的细节

• 端口自动连线：文档特别说明，你只需要添加端口的位置，PSCAD 会自动为端口生成引线和箭头，不需要手动画。
• 参数占位符：在 Fortran 脚本里，像 $Gain 这样的写法会被自动替换成用户在参数表单里填的具体数值，这是 PSCAD 的机制。
• 表单布局：你可以控制参数对话框的大小、分类树宽度、帮助面板宽度等（form_width, form_height 等属性）。
• 启用/可见性条件：很多方法都有 enable 和 visible 参数，可以用逻辑表达式（如 $Type == 1）动态控制端口、图形或参数是否出现。