# Ligralpy

**Repository Path**: py2cn/ligralpy

## Basic Information

- **Project Name**: Ligralpy
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-06-28
- **Last Updated**: 2022-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ligral Frontend 适配Ligral语言的前端
<img src="https://gitee.com/hzy15610046011/ligralpy/badge/star.svg?theme=dark" alt="star" loading="lazy">

## 项目介绍
### 什么是Ligral?

Ligral是一个基于文本的仿真语言，旨在替代**Simulink**进行仿真，通过与框图等效的文本语言描述仿真对象，并解释/编译而后求解。

Ligral项目的地址：
[https://gitee.com/junruoyu-zheng/ligral](https://gitee.com/junruoyu-zheng/ligral)

### 什么是LigralPy？
LigralPy是专为Ligral语言打造的可视化仿真系统，基于Web技术搭建。由于服务端使用Python语言编写，且提供Python语言调用的接口，故名为LigralPy。

![流程图编辑器](pics/flowchart-editor.png)

### LigralPy的优点
相比其他类型的系统仿真软件，LigralPy主要有以下优点：
- 下载安装方便
    - 依赖包成熟且下载体积小，Windows/ MacOS/ Linux 全平台支持。
    - 针对MacOS/Linux/WSL，提供基于Docker的容器化部署方案，通过**国内镜像源**一键快速获取LigralPy。
- 契合开源数据分析生态
    - 所有接口实现均开源，用户可自行编写程序与Ligral协同工作，从而提升开发效率。


### LigralPy项目开发背景
本项目的开发者曾开发**PyMiner**项目，目的是建立一个开源的类Matlab程序。但最终我们发现，Matlab内置的算法才是最重要的价值所在。在一系列算法工具箱中，最为不可替代的功能当属**Simulink**，它被广泛用于控制系统仿真，在工业界、学术界有着几乎不可替代的地位。

因此，我们最终决定瞄准小切口，实现一个类似于Simulink功能、但代码上和其完全无关的开源软件。这个开源软件或许不能直接服务于工业界和实际生产，但可以用在教育教学方面——自然，也可以丰富我国开源软件的生态。

同为PyMiner核心开发者的 [junruoyu-zheng](https://gitee.com/junruoyu-zheng) 开发了基于`C#`的Ligral，这样便有了核心算法程序。如果有一个用户友好的界面，便可以让更多的人来认识Ligral。这也是LigralPy项目启动的初衷。

## 项目图片预览

![流程图编辑器](pics/flowchart-editor.png)

![仿真结果](pics/simulation-result.png)

## 用户安装
以下的教程为一般的安装步骤，适用于所有平台。

在本节最后部分，我们还展示了基于docker的快速安装方式，如果电脑中装有docker，可以通过docker进行安装。

特别的，由于Ligral主程序依赖于.NET运行时，因此在MacOS/Linux上安装较为繁琐。由是，**若您使用的电脑为MacOS/Linux，建议优先使用docker安装此仿真系统**

### 安装Python
首先，需要安装Python。如果你的电脑上还没有Python，可以戳这里下载。

- [Windows Python](https://mirrors.huaweicloud.com/python/3.8.8/python-3.8.8.exe)
- [MacOS Python](https://mirrors.huaweicloud.com/python/3.8.8/python-3.8.8.exe)

以上的下载链接使用的是华为云的镜像，速度高于官网。

- 不过，如果你使用的是Linux操作系统，你很可能已经相当熟悉Python。加之Linux操作系统的软件包分发较为复杂，因此安装链接就不在此处放出。

Python语言的安装过程网上已有很多，在这里由于篇幅所限，不在赘述。

### 安装Ligral
Ligral发布在这里：
- https://gitee.com/junruoyu-zheng/ligral/releases

可以在这个仓库中下载最新版本的Ligral。

### 安装LigralPy
在你的电脑的终端中，执行如下命令：
```
python -m pip install LigralPy
```
如果你看到了`Successfully installed ligralpy`这样的信息，说明安装成功。如果安装不成功且无法排除问题，请联系本项目开发者。

### 启动LigralPy
执行如下命令：
```
python -m LigralPy
```
会显示这样的信息：
```
INFO:LigralPy.server.chart_receiver:chart udp receiver started at ('127.0.0.1', 8784)
 * Serving Flask app 'LigralPy.server.server' (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
INFO:werkzeug: * Running on http://127.0.0.1:5394 (Press CTRL+C to quit)
```
以上信息说明LigralPy的主服务已经启动。将信息中的链接`http://127.0.0.1:5394`复制到浏览器中访问，即可打开仿真页面。

### 使用docker安装
Docker主要适用于`Mac OS`和`Linux`电脑，或是开启`WSL`的`Windows`电脑。
- 如果你是Windows电脑用户，也可安装Linux虚拟机进行体验。
```sh
docker pull registry.cn-beijing.aliyuncs.com/pyminer/ligralpy:v0.3.0
# 运行docker镜像，并将ligralpy容器中的5394端口，映射到电脑的8080端口。同时，将希望映射的文件夹映射到容器的/root/simulation文件夹。
docker run -it -p 8080:5394 -v {希望映射的文件夹}:/root/simulation registry.cn-beijing.aliyuncs.com/pyminer/ligralpy:v0.3.0 python3 -m LigralPy
```
随后可以使用浏览器访问**http://localhost:8080**（注意端口号是8080，而不是5394，这是由命令中`-p`参数指定的）

## 页面操作
如果你想查看帮助文档，可以查看这里：[用户文档](docs/README.md)

## 技术属性
### 开发语言
#### 后端
- Python语言，基础功能仅使用标准库、Flask服务器框架以及Numpy等科学计算基础设施。
- 需要安装Ligral的可执行文件，并且添加到系统环境变量
#### 前端
- Vue3+TypeScript+Element Plus
- 流程图使用JSPlumb社区版。其中，流程图拖动时添加拐点约束的算法，社区版不集成，为本项目开发者自行实现。

## 开发者安装
### 前端安装依赖和启动
```
yarn install
yarn serve
yarn build
```
### 后端安装依赖和启动
```
cd backend
pip install flask
python run.py
```

### 发布
```
python build_web.py
python setup.py bdist_wheel
```

## 项目文档
[用户文档](docs/README.md)

## 开源协议
本项目涉及到的开源项目主要有：
- Python生态系统(GPL)
- JSPlumb社区版(MIT)
- ECharts(Apache)
- Vue(MIT)
- ElementUI(MIT)

## 更新日志
- 0.3.0
    - 增加框选后批量拖动节点的功能

- 0.2.1
    - 修改徽标
    - 增加新建项目和打开项目时路径校验，优化交互逻辑

- 0.2.0
    - 支持Ligral中`in/out-port-variable`为`true`的节点变更输入/输出端口的数量。
    - 用户点击自定义的路由的“参数编辑”功能时，会跳转到路由编辑的页面。对于其他类型的节点，网页的行为不变。
    - 增加了中文翻译的内容
    - 增加了界面主题颜色的全局变量，目前仅为演示

- 0.1.1
    - 从直线改为可自动添加拐点的连线。
    - 增加了UDP转串口的异步数据交换功能。
    - 修改了底层有关节点类型方面的结构。

- 0.1.0
    - 初始化项目
    - 构建基本的连线系统
    - 增加添加、删除节点以及保存的功能