GeckoCIRCUITS 是一款由苏黎世联邦理工学院（ETH）开发的开源电力电子仿真软件，以其高仿真速度、直观的用户界面

和强大的功能而著称。 在电力电子系统设计与仿真中，用户常常需要定制化工具来满足特定需求，例如实现离散时间控制器

等特殊功能模块。由于GeckoCIRCUITS的模块库可能未涵盖所有应用场景，开发自定义工具模块显得尤为重要。本文旨在

详细介绍在GeckoCIRCUITS中开发新工具模块的方法，涵盖从环境准备到模块集成的完整流程，帮助用户扩展软件功能，

提升仿真效率。

一、开发环境准备

1.1 获取GeckoCIRCUITS源代码

GeckoCIRCUITS的源代码托管在GitHub上，用户需访问官方仓库（https://github.com/geckocircuits/GeckoCIRCUITS）

进行下载。 下载后，解压文件至本地目录，确保路径不含中文或特殊字符以避免编译错误。建议使用Git进行版本控制，便于

后续更新和协作开发。

1.2 安装开发工具链

GeckoCIRCUITS基于Java开发，因此需安装以下工具：

Java Development Kit (JDK)‌：推荐使用JDK 11或更高版本，确保兼容性。

集成开发环境 (IDE)‌：推荐使用IntelliJ IDEA或Eclipse，提供代码补全、调试和版本控制集成。

构建工具‌：Maven或Gradle，用于管理项目依赖和构建过程。

安装完成后，配置环境变量，确保命令行可识别java和mvn（或gradle）命令。

1.3 导入项目至IDE

在IDE中导入GeckoCIRCUITS项目：

打开IDE，选择“Import Project”。

导航至GeckoCIRCUITS源代码目录，选择pom.xml（Maven）或build.gradle（Gradle）文件。

等待依赖项下载完成，构建项目结构。

项目结构通常包含以下关键目录：

src/main/java：核心Java源代码。

src/main/resources：资源文件（如国际化字符串、配置文件）。

src/test/java：测试代码。

二、理解GeckoCIRCUITS模块体系

2.1 模块化设计理念

GeckoCIRCUITS采用模块化设计，每个功能模块（如电源、控制器、测量工具）均为独立的Java类，继承自AbstractComponentTyp基类。 模块通过接口定义输入/输出端口、属性和行为，实现高内聚低耦合。

2.2 核心类与接口

AbstractComponentTyp‌：所有模块的基类，定义通用属性和方法（如名称、尺寸、I/O端口）。

ControlTypeInfo‌：描述模块类型信息（如名称、标签、国际化键）。

TerminalControlInput/Output‌：定义输入/输出端口，支持标签和连接逻辑。

AbstractControlCalculatable‌：实现模块的计算逻辑（如仿真步进、控制算法）。

2.3 模块生命周期

初始化‌：在仿真开始时，GeckoCIRCUITS调用initialize()方法，设置模块属性和端口连接。

仿真步进‌：每个时间步，调用step()方法执行计算（如更新控制信号）。

终止‌：仿真结束时，调用shutdown()方法释放资源。

三、开发新工具模块的步骤

3.1 定义模块需求

以开发“离散时间比例-谐振控制器（Digital PR Controller）”为例，需求如下：

输入：参考电压（input）、比例增益（kp）、谐振增益（kr）、角频率（wo）、采样频率（fs）。

输出：控制信号（output）。

功能：实现离散时间域的PR控制算法。

3.2 创建模块类

在src/main/java/ch/technokrat/gecko/geckocircuits/control目录下新建ReglerDPRCONTROL.java文件，继承RegelBlock（控制模块基类）。

java

Copy Code

package ch.technokrat.gecko.geckocircuits.control;

import ch.technokrat.gecko.geckocircuits.allg.AbstractComponentTyp;

import ch.technokrat.gecko.geckocircuits.control.calculators.AbstractControlCalculatable;

import ch.technokrat.gecko.geckocircuits.control.calculators.DPRControlCalculator;

import ch.technokrat.gecko.i18n.resources.I18nKeys;

import java.awt.Window;

public final class ReglerDPRCONTROL extends RegelBlock {

    private static final int BLOCK_WIDTH = 5;

    public static final ControlTypeInfo tinfo = new ControlTypeInfo(

        ReglerDPRCONTROL.class,

        "DIGITAL_PR_CTRL",

        I18nKeys.DIGITAL_PR_CONTROL

    );

    public ReglerDPRCONTROL() {

        super();

        // 定义输入端口

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "input"));

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "kp"));

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "kr"));

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "wo"));

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "fs"));

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "wrc"));

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "max"));

        XIN.add(new TerminalControlInputWithLabel(this, -3, -XIN.size(), "min"));

        // 定义输出端口

        YOUT.add(new TerminalControlOutputWithLabel(this, 3, -YOUT.size(), "output"));

    }

    @Override

    public int getBlockWidth() {

        return BLOCK_WIDTH * dpix;

    }

    @Override

    public String[] getOutputNames() {

        return new String[]{"output"};

    }

    @Override

    public I18nKeys[] getOutputDescription() {

        return new I18nKeys[]{};

    }

    @Override

    public double getXShift() {

        return 1 / 2.0;

    }

    @Override

    public AbstractControlCalculatable getInternalControlCalculatableForSimulationStart() {

        return new DPRControlCalculator();

    }

    @Override

    protected String getCenteredDrawString() {

        return "DIGITAL\nPR\nCTRL";

    }

    @Override

    protected final Window openDialogWindow() {

        return new DialogWindowWithoutInput(this);

    }

}

3.3 实现计算逻辑

创建DPRControlCalculator.java，继承AbstractControlCalculatable，实现PR控制算法：

java

Copy Code

package ch.technokrat.gecko.geckocircuits.control.calculators;

import ch.technokrat.gecko.geckocircuits.control.calculators.AbstractControlCalculatable;

import ch.technokrat.gecko.geckocircuits.control.calculators.DPRControlCalculator;

import ch.technokrat.gecko.geckocircuits.control.calculators.DPRControlCalculator;

public class DPRControlCalculator extends AbstractControlCalculatable {

    private double input;

    private double kp;

    private double kr;

    private double wo;

    private double fs;

    private double wrc;

    private double max;

    private double min;

    private double output;

    @Override

    public void setInput(double input, int index) {

        switch (index) {

            case 0: this.input = input; break;

            case 1: this.kp = input; break;

            case 2: this.kr = input; break;

            case 3: this.wo = input; break;

            case 4: this.fs = input; break;

            case 5: this.wrc = input; break;

            case 6: this.max = input; break;

            case 7: this.min = input; break;

        }

    }

    @Override

    public double getOutput(int index) {

        if (index == 0) {

            // 实现PR控制算法

            double error = input - output;

            double integral = integral + error * (1 / fs);

            double derivative = (error - prevError) / (1 / fs);

            prevError = error;

            output = kp * error + kr * integral + wo * derivative;

            output = Math.max(min, Math.min(max, output));

            return output;

        }

        return 0;

    }

    @Override

    public void reset() {

        integral = 0;

        prevError = 0;

    }

}

3.4 添加国际化支持

在src/main/resources/i18n/strings.properties中添加模块描述：

properties

Copy Code

DIGITAL_PR_CONTROL=Digital PR Controller

input=Input

kp=Proportional Gain

kr=Resonant Gain

wo=Angular Frequency

fs=Sampling Frequency

wrc=Resonant Frequency

max=Maximum Output

min=Minimum Output

output=Output

3.5 构建与测试

构建项目‌：在命令行中运行mvn clean install，生成JAR文件。

集成至GeckoCIRCUITS‌：将生成的JAR文件复制到GeckoCIRCUITS的lib目录下。

启动软件‌：打开GeckoCIRCUITS，新模块应出现在工具栏的“Custom Control”类别中。

四、模块优化与调试

4.1 性能优化

减少计算复杂度‌：避免在仿真步进中执行耗时操作（如动态内存分配）。

使用缓存‌：对频繁访问的数据（如模块参数）进行缓存。

并行化‌：利用Java多线程处理独立计算任务。

4.2 调试技巧

日志输出‌：在代码中添加System.out.println或使用日志框架（如Log4j）记录关键变量。

断点调试‌：在IDE中设置断点，逐步执行代码，观察变量变化。

单元测试‌：为模块编写JUnit测试，验证输入/输出逻辑。

4.3 常见问题解决

模块未显示‌：检查ControlTypeInfo的name和I18nKey是否与资源文件匹配。

仿真崩溃‌：确保所有输入端口已连接，且参数值在有效范围内。

性能下降‌：分析仿真日志，定位耗时操作。

五、模块发布与共享

5.1 打包模块

创建META-INF/services目录，添加ch.technokrat.gecko.geckocircuits.control.ControlTypeInfo文件，内容为模块类的全限定名（如ch.technokrat.gecko.geckocircuits.control.ReglerDPRCONTROL）。

使用Maven构建JAR文件，确保包含所有依赖项。

5.2 发布至社区

将JAR文件上传至GitHub仓库或论坛，提供模块描述、使用示例和源代码。

在GeckoCIRCUITS社区中分享模块，邀请其他用户测试和反馈。

六、总结与展望

本文详细介绍了在GeckoCIRCUITS中开发新工具模块的方法，涵盖环境准备、模块设计、实现、调试和发布的全流程。通过自定义模块，用户可扩展软件功能，满足特定仿真需求。未来，随着电力电子技术的不断发展，模块化开发将进一步提升GeckoCIRCUITS的灵活性和适用性。

6.1 关键点回顾

模块化设计‌：基于Java的面向对象编程，实现高内聚低耦合。

国际化支持‌：通过资源文件实现多语言界面。

性能优化‌：减少计算复杂度，利用缓存和并行化。

社区共享‌：通过开源平台发布模块，促进协作创新。

6.2 未来方向

自动化测试‌：集成持续集成（CI）系统，自动验证模块功能。

可视化配置‌：开发图形化界面，简化模块参数设置。

AI辅助设计‌：利用机器学习优化控制算法参数。

通过本文的指导，用户可快速掌握GeckoCIRCUITS模块开发技能，为电力电子系统仿真提供更强大的工具支持。