Home
Welcome to the FlowControl wiki! Learn more about How It Works and How To Use.
The FlowControl toolbox is an open-source toolbox addressing the simulation and control of 2D incompressible flows. It aims at providing a user-friendly way to simulate flows with actuators and sensors, and a possibility to readily define new use-cases.
The primary goal of the toolbox is the design and implementation of feedback control algorithms, but it may be used for a variety of other topics such as model reduction or identification, actuator and sensor placement study...
The toolbox is shipped with two benchmarks for flow control and allows for easy implementation of new cases.
The core of the toolbox is in Python and relies on FEniCS 2019.1.0 as a backend.
[[illustrations/fenics_banner.png]
- By default, the toolbox integrates in time the
Incompressible Navier-Stokes equations. For a 2D flow defined by its velocity
${v}({x}, t) = [v_1({x}, t), v_2({x}, t)]$ and pressure$p({x}, t)$ inside a domain${x} = [x_1, x_2] \in\Omega$ , the equations read as follows:
- The only numerical parameter of the non-dimensional equations, the Reynolds number defined as
$Re = \frac{UL}{\nu}$ , balances convective and viscous terms.
The toolbox allows the user to define actuators and sensors for forcing the flow. It also provides utility for controller design and implementation. See the examples given below.
Two classic oscillator flows used for flow control are shipped with the current code.
| Use-case | Description | Feedback configuration |
|---|---|---|
| Cylinder | Flow past a cylinder at Re=100 | SISO |
| Cavity | Flow over an open cavity at Re=7500 | SISO |
- For the flow past a cylinder at Re=100, see e.g.:
- For the flow over an open cavity at Re=7500, see e.g.:
-
For discretization in space, the Finite Element Method is used, using default continuous Galerkin elements of order 2 (for each component of the velocity) and 1 (for the scalar pressure).
-
For the time integration, a linear multistep semi-implicit method is used (the nonlinear term is extrapolated with a second-order Adams–Bashforth scheme, while the viscous term is treated implicitly).
-
The equations are implemented using a perturbation formulation:
- the field
$v(x,t)$ is decomposed as$v(x,t) = V(x) + v'(x, t)$ , -
$V(x)$ is computed first, - then, we can compute the time evolution of
$v'(x,t)$ .
- the field
-
To some extent, the toolbox aims at making the equations, numerical integration schemes and solvers replaceable by user-defined ones.
The following articles were based on previous versions of the code:
- Jussiau, W., Leclercq, C., Demourant, F., & Apkarian, P. (2022). Learning linear feedback controllers for suppressing the vortex-shedding flow past a cylinder. IEEE Control Systems Letters, 6, 3212-3217.
- Jussiau, W., Leclercq, C., Demourant, F., & Apkarian, P. (2024). Data-driven stabilization of an oscillating flow with linear time-invariant controllers. Journal of Fluid Mechanics, 999, A86.
The conda environment required to run the code can be extracted from the file environment.yml. Additional path tweaking may be required for all FEniCS (dolfin module) and custom modules to be found.
[coming soon]
The simulation revolves around the abstract class FlowSolver that implements core features such as loading mesh, defining function spaces, trial/test functions, variational formulations, numerical schemes and solvers, handling the time-stepping and exporting information. The class is abstract as it does not implement a simulation case per se, but only provides utility for doing so. It features two abstract methods, that are redefined for each use-case:
-
_make_boundariesprovides a definition and naming of the boundaries of the mesh in a pandas DataFrame.
@abstractmethod
def _make_boundaries(self) -> pd.DataFrame:
pass-
_make_bcsprovides a description of the boundary conditions on the boundaries defined above, in a dictionary.
@abstractmethod
def _make_bcs(self) -> dict[str, Any]:
passFor the two aforementioned examples, these methods are reimplemented in the classes CylinderFlowSolver and CavityFlowSolver that inherit from FlowSolver.
In order to perform sensing and actuation (in order to close the loop), dedicated classes Sensor and Actuator are proposed. They are not aimed at being instantiated, but rather inherited.
-
Sensoris an abstract class that provides a methodeval(self, up: dolfin.Function) -> float. ClassesSensorPoint(point probe) andSensorIntegral(integration on a subdomain) are examples of subclasses that implement theevalmethod. - Likewise,
Actuatoris an abstract class that encapsulates adolfin.Expressionamong other elements, and embeds it in the variational formulations.
The sensors and actuators are attached to a FlowSolver object as a list, embedded in the ParamControl object. The call to Sensors and Actuators is made automatically by FlowSolver.
By attaching several sensors or actuators, it is possible to use Multiple-Input, Multiple-Output controllers in the loop.
In the example below (for the cylinder use-case), we are creating an actuator acting on boundary conditions and three point probes at different locations. They are gathered in a ParamControl object, which is passed as an argument when creating a CylinderFlowSolver.
# Actuator
actuator_bc = ActuatorBCParabolicV(angular_size_deg=10)
# Sensors
sensor_feedback = SensorPoint(sensor_type=SENSOR_TYPE.V, position=np.array([3, 0]))
sensor_perf_1 = SensorPoint(sensor_type=SENSOR_TYPE.V, position=np.array([3.1, 1]))
sensor_perf_2 = SensorPoint(sensor_type=SENSOR_TYPE.V, position=np.array([3.1, -1.3]))
# Gather actuators and sensors in ParamControl object
params_control = ParamControl(
sensor_list=[sensor_feedback, sensor_perf_1, sensor_perf_2],
actuator_list=[actuator_bc],
)Once a use-case has been defined by implementing the corresponding class, the basic feedback syntax has the following philosophy:
# Instantiate and initialize FlowSolver object
fs = CylinderFlowSolver(...)
fs.compute_steady_state(...)
fs.initialize_time_stepping(...)
# Instantiate Controller (e.g. load from .mat file)
Kss = Controller.from_file(...)
# Time loop
y_meas = fs.y_meas
for _ in range(fs.params_time.num_steps):
u_ctrl = Kss.step(y=-y_meas[0], dt=fs.params_time.dt)
y_meas = fs.step(u_ctrl=u_ctrl)See examples for a more detailed description.
No meshing tools are shipped with this code, but gmsh (and its Python API) are suggested for generating meshes. The mesh should be exported to xdmf format, which can be reached thanks to meshio.
Paraview is suggested for visualizations, whether it be for csv timeseries or fields saved as xdmf.
The toolbox provides additional utility related to flow control:
- Compute dynamic operators A, B, C, D and mass matrix E,
- Restart a simulation from a previous one,
- Arbitrary number of sensors (for feedback or performance),
- Export time series (measurements from sensors, perturbation kinetic energy...) and fields for visualization,
- Parallel execution native to FEniCS,
- To some extent, easy modification of the equations, numerical schemes and solvers used for time simulation,
- Can be used as backend in an optimization tool (as in Jussiau, W., Leclercq, C., Demourant, F., & Apkarian, P. (2022). Learning linear feedback controllers for suppressing the vortex-shedding flow past a cylinder. IEEE Control Systems Letters, 6, 3212-3217.).
The current roadmap is as follows:
- Complete the documentation 📖,
- Refactor and release additional control-related tools,
- Update the project to FEniCSx,
- Sort and check all utility functions,
- General form for operator computation,
- Docker/venv/pip.
Also, I highly recommend FEniCS documentation, FEniCS forum (and potentially the BitBucket repository) for problems regarding FEniCS 2019.1.0 itself.
This README has been optimized for accessibility based on GitHub's blogpost "Tips for Making your GitHub Profile Page Accessible".