Skip to content

Commit a0c1d40

Browse files
committed
chore: update readme.
1 parent fe50114 commit a0c1d40

File tree

2 files changed

+87
-10
lines changed

2 files changed

+87
-10
lines changed

README.md

+45-6
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,46 @@ ospf introduces a concept called "intermediate expression" to facilitate DDD-bas
2121
- they are grammatically equivalent to variables, having a global scope and static lifetime.
2222
- they can be constructed through an anonymous polynomial.
2323

24-
<!-- add examples -->
24+
### Arithmetic Intermediate Expression:
25+
26+
The initial purpose of designing intermediate expressions was to reduce redundancy in mathematical models. Therefore, the most basic arithmetic intermediate expressions are constructed using a polynomial, allowing users to replace all identical polynomials with this intermediate expression anywhere in the model.
27+
28+
$$
29+
ExprSymbol = \sum_{i} x_{i} \\ \; \\
30+
min \quad ExprSymbol \\ \; \\
31+
s.t. \quad ExprSymbol \leq 1
32+
$$
33+
34+
ospf automatically replaces each arithmetic intermediate expressions with specific polynomials when translating the model into interfaces for specific solvers. This translation process is transparent to the user, so the user does not need to know how the arithmetic intermediate expressions are implemented through which variables and operations.
35+
36+
Thus, we can divide the maintainers of mathematical models into two roles: <em>"intermediate expressions maintainer"</em> and <em>"user of intermediate expressions"</em>. The intermediate expressions maintainers are responsible for defining and implementing intermediate expressions, while users of intermediate expressions do not concern themselves with the implementation of intermediate expresssions. They only focus on the definition and behavior of intermediate expressions and use these intermediate expressions to describe business logic in mathematical models.
37+
38+
This engineering practice is similar to <strong><em>Object-Oriented Design</em></strong> (OOD), where defining a class encapsulates variables and functions with the same semantics, and users only need to focus on their behavior without concerning themselves with their implementation. With such a foundation, we can then begin to introduce DDD.
39+
40+
### Functional Intermediate Expression:
41+
42+
Building upon the concept of arithmetic intermediate expressions, ospf can also encapsulate non-arithmetic expressions such as logical operations into intermediate expressions.
43+
44+
$$
45+
FuncSymbol = \bigvee_{i} x_{i} = Or(x_{1}, \, x_{2}, \, .. \, , \, x_{i}) \\ \; \\
46+
s.t. \quad FuncSymbol = 1
47+
$$
48+
49+
When ospf translates the model into interfaces for specific solvers, it automatically adds the intermediate variables and constraints required for each intermediate expressions. This translation process is transparent to the users, so the users don't need to know how the intermediate expressions are implemented through which intermediate variables and constraints. For example, the expression $FuncSymbol = \bigvee_{i} x_{i}$ will be translated as follows:
50+
51+
$$
52+
s.t. \quad y = 1, \; \\ \; \\
53+
\begin{cases}
54+
y \geq \frac{x_{i}}{\sup_{\leq}(x_{i})}, & \sup_{\leq}(x_{i}) > 1 \\ \;
55+
y \geq x_{i}, & else
56+
\end{cases} \\ \; \\
57+
y \leq \sum_{i} x_{i}, \; \forall i \\ \; \\
58+
y \in \{ 0, 1 \}
59+
$$
60+
61+
Of course, you can also extend these intermediate expressions according to your own business requirements. At this point, you need to implement some interfaces to let ospf know which intermediate variables and constraints need to be added for these intermediate expressions.
62+
63+
The <em>ospf-core</em> only maintains arithmetic and logical functions. In fact, we can design and implement functional intermediate expressions based entirely on the domain, as part of domain engineering. For specific references, you can refer to the development package for specific problem domains in the <em>ospf-framework</em>.
2564

2665
## Components
2766

@@ -45,11 +84,11 @@ each OSPF implementation consists of the following components:
4584
- <strong>core-plugin-heuristic</strong>: meta-heuristic algorithm plugins containing implementations of various common meta-heuristic algorithms.
4685
- <strong>framework</strong>: problem-specific frameworks containing implementations of data processing, mathematical models, and solving algorithms tailored to specific problems. All designs and implementations are non-intrusive, allowing users to use them out of the box or extend them seamlessly, integrating with other frameworks or components.
4786
- <strong>framework-plugin-XXX</strong>: framework plugins implementing functionalities requiring middleware involvement, such as data persistence, asynchronous message communication.
48-
- <strong>bpp1d</strong>: 1d bin packing problem development package containing implementations of data processing, mathematical models, and solving algorithms for various one-dimensional bin packing problems.
49-
- <strong>bpp2d</strong>: 2d bin packing problem development package containing implementations of data processing, mathematical models, and solving algorithms for various two-dimensional bin packing problems.
50-
- <strong>bpp3d</strong>: 3d bin packing problem development package containing implementations of data processing, mathematical models, and solving algorithms for various three-dimensional bin packing problems.
51-
- <strong>csp1d</strong>: 1d cutting stock problem development package containing implementations of data processing, mathematical models, and solving algorithms for various one-dimensional cutting stock problems.
52-
- <strong>csp2d</strong>: 2d cutting stock problem development package containing implementations of data processing, mathematical models, and solving algorithms for various two-dimensional cutting stock problems.
87+
- <strong>bpp1d</strong>: 1D <strong><em>Bin Packing Problem</em></strong> (BPP) development package containing implementations of data processing, mathematical models, and solving algorithms for various 1D BPPs.
88+
- <strong>bpp2d</strong>: 2D <strong><em>Bin Packing Problem</em></strong> (BPP) development package containing implementations of data processing, mathematical models, and solving algorithms for various 2D BPPs.
89+
- <strong>bpp3d</strong>: 3D <strong><em>Bin Packing Problem</em></strong> (BPP) development package containing implementations of data processing, mathematical models, and solving algorithms for various 3D BPPs.
90+
- <strong>csp1d</strong>: 1D <strong><em>Cutting Stock Problem</em></strong> (CSP) development package containing implementations of data processing, mathematical models, and solving algorithms for various 1D CSPs.
91+
- <strong>csp2d</strong>: 2D <strong><em>Cutting Stock Problem</em></strong> (CSP) development package containing implementations of data processing, mathematical models, and solving algorithms for various 2D CSPs.
5392
- <strong>gantt-scheduling</strong>: gantt scheduling problem development package containing implementations of data processing, mathematical models, and solving algorithms for various Gantt chart scheduling problems. It can be used for scheduling and planning problems such as <strong><em>Advanced Production Scheduling</em></strong> (APS), <strong><em>Lot Scheduling Problem</em></strong> (LSP), etc.
5493
- <strong>network-scheduling</strong>: network scheduling problem development package containing implementations of data processing, mathematical models, and solving algorithms for various network scheduling problems. It can be used for scheduling and planning problems such as <strong><em>Vehicle Routing Problem</em></strong> (VRP), <strong><em>Facility Location Problem</em></strong> (FLP), etc.
5594

README_ch.md

+42-4
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,50 @@ ospf 是一个针对复杂的运筹优化算法中建模与编码过程的解决
1616

1717
ospf 提供了一种命名为“中间值”的概念,以实现基于 DDD 的建模方式。中间值在数学模型中用于表示运算的中间结果,它可以帮助简化模型的表示,并使得模型更易于理解和维护。中间值有以下特性:
1818

19-
- 指代一个被存储起来的具名的多项式
20-
- 语义上等价于匿名的多项式
19+
- 指代一个被存储起来的具名的表达式
20+
- 语义上等价于匿名的表达式
2121
- 文法上等价于变量,拥有全局作用域以及静态生命周期
22-
- 可以通过一个匿名的多项式构造
2322

24-
<!-- 添加样例 -->
23+
### 算术中间值
24+
25+
中间值最开始的设计目的是为了减少数学模型中的重复,所以最基本的算术中间值就是通过一个多项式来构建,然后使用者就可以在模型的任何地方使用该中间值替代所有同样的多项式。
26+
27+
$$
28+
ExprSymbol = \sum_{i} x_{i} \\ \; \\
29+
min \quad ExprSymbol \\ \; \\
30+
s.t. \quad ExprSymbol \leq 1
31+
$$
32+
33+
ospf 会在将模型翻译到具体求解器的接口时,自动将把每个算术中间值替换为具体的多项式,这个翻译过程对于使用者而言是无感知的,因此使用者并不需要知道这个算术中间值是通过什么变量通过什么运算实现的。
34+
35+
那么,我们就可以把数学模型的维护者划分为“中间值维护者”以及“使用中间值维护数学模型者”两个角色。中间值维护者负责定义以及实现中间值,使用中间值维护数学模型者不关注中间值的实现,只关注中间值的定义与行为,并使用这些中间值在数学模型中描述业务逻辑。
36+
37+
这个工程实践,和面向对象设计(OOD)中定义一个类把相同语义的变量、函数封装起来,使用者只需关注其行为,无需关注其实现,是一样的。有了这样的基础之后,我们就可以开始引入 DDD 了。
38+
39+
### 函数中间值
40+
41+
基于算术中间值的思想,ospf 同样可以把类似逻辑运算表达式等非算术表达式封装到中间值中。
42+
43+
$$
44+
FuncSymbol = \bigvee_{i} x_{i} = Or(x_{1}, \, x_{2}, \, .. \, , \, x_{i}) \\ \; \\
45+
s.t. \quad FuncSymbol = 1
46+
$$
47+
48+
ospf 会在将模型翻译到具体求解器的接口时,自动添加每个函数中间值所需的中间变量以及约束。这个翻译过程对于使用者而言是无感知的,因此使用者并不需要知道这个函数中间值是通过什么中间变量以及约束实现的。比如上面的这个 $FuncSymbol = \bigvee_{i} x_{i}$ 就会被翻译成:
49+
50+
$$
51+
s.t. \quad y = 1, \; \\ \; \\
52+
\begin{cases}
53+
y \geq \frac{x_{i}}{\sup_{\leq}(x_{i})}, & \sup_{\leq}(x_{i}) > 1 \\ \;
54+
y \geq x_{i}, & else
55+
\end{cases} \\ \; \\
56+
y \leq \sum_{i} x_{i}, \; \forall i \\ \; \\
57+
y \in \{ 0, 1 \}
58+
$$
59+
60+
当然,你也可以根据自己的业务需求,拓展这些函数中间值。这个时候你要实现一些接口,以让 ospf 知道这个函数中间值需要添加哪些中间变量以及约束。
61+
62+
ospf-core 本身只维护有算术运算符以及逻辑运算符,实际上我们完全可以基于领域去设计并实现函数中间值,以作为领域工程的一部分。具体可以参考 ospf-framework 中面向特定问题的开发包。
2563

2664
## 组件
2765

0 commit comments

Comments
 (0)