Acoplamiento de código con Precice: simulaciones multifísicas en Python

tl; dr

Las simulaciones multifísicas a menudo requieren el acoplamiento de múltiples solucionadores especializados. Precice es una biblioteca de acoplamiento de código abierto y de código abierto que permite simulaciones multifísicas particionadas en Python. Este tutorial muestra cómo acoplar Fipy con otro solucionador usando Precice, cubriendo la instalación, la implementación del adaptador, la configuración y las trampas comunes. Aprenderá cuándo usar el acoplamiento particionado, cómo configurar el intercambio de datos y cómo depurar los problemas típicos.

Introducción: Cuando un solucionador no es suficiente

Muchos problemas científicos involucran múltiples procesos físicos que interactúan. Por ejemplo:

• Transferencia de calor acoplada con flujo de fluido (transferencia de calor conjugada)
• Mecánica estructural que interactúa con la dinámica de fluidos (interacción fluido-estructura)
• Electroquímica junto con fenómenos de transporte (modelado de batería)

Fipy sobresale en la resolución de ecuaciones diferenciales parciales (PDES) para problemas de transporte, difusión y campo de fase. Sin embargo, algunos escenarios multifísicas requieren el acoplamiento de Fipy con un solucionador especializado para otro dominio de física, como OpenFoam para Fluid Dynamics o un código estructural personalizado.

Code Coupling es la práctica de conectar dos o más códigos de simulación independientes para que intercambian datos durante el cálculo. Aquí es donde entra precice (infraestructura de acoplamiento particionado para ecuaciones continuas).

¿Por qué usar Precise?

Precisión proporciona:

• Acoplamiento agnóstico de idiomas: Conectar solucionadores escritos en C++, Python, Fortran, etc.
• Mapeo de datos flexible: manejar la interpolación de malla a malla entre rejillas no coincidentes
• Coordinación de pasos en el tiempo: Apoyar esquemas de acoplamiento explícitos, implícitos y cuasi-Newton
• Escalabilidad paralela: diseñado para entornos de computación de alto rendimiento
• Comunidad activa: utilizada en la investigación y la industria, con buena documentación

Para los usuarios de Fipy, Precice abre la puerta a sólidos flujos de trabajo multifísicos sin crear infraestructura de acoplamiento desde cero.

Soludores particionados vs monolíticos

Antes de sumergirse, comprenda los dos enfoques principales de la multifísica:

Cuándo elegir el acoplamiento dividido con Precice:

• Dispone de solucionadores optimizados y fiables para la física individual (p. ej., Fipy para difusión, OpenFoam para Flow)
• la física está vaga o moderadamente acoplada
• Desea aprovechar las bases de código y las comunidades existentes
• Necesitas flexibilidad para probar diferentes combinaciones de solucionador

Cuando el monolítico podría ser mejor:

• Acoplamiento extremadamente ajustado que requiere tratamiento implícito a nivel de álgebra lineal
• Simulaciones de HPC críticas por rendimiento donde la sobrecarga de comunicación es inaceptable
• Física muy nueva donde aún no existe un solucionador especializado

Para muchas aplicaciones de investigación, acoplamiento particionado con Precice es la elección pragmática.

Visión Conceptual: Cómo funciona Precice

Precice sigue una arquitectura client-server:

1. Resolver A (por ejemplo, Fipy) se ejecuta como cliente de precisión
2. Solver b (otro código) se ejecuta como otro cliente de precisión
3. precice se ejecuta como un proceso separado (el servicio de acoplamiento) que gestiona la comunicación y el mapeo de datos
4. En las interfaces de acoplamiento, los solucionadores intercambian datos de límites (p. ej., temperatura, flujo de calor, velocidad) a través de Precice
5. Manejadores de precisión:
   • Mapeo de malla cuando las mallas de interfaz no coinciden
   • Sincronización de paso de tiempo
   • Relajación de datos y relajación insuficiente para mejorar la convergencia
   • Esquemas de acoplamiento (explícito, implícito, cuasi-newton)

El beneficio clave: cada solucionador permanece inconsciente de los detalles internos del otro. Solo necesitan saber cómo enviar/recibir datos en su límite a través de la API de Precice.

requisitos previos

Antes de comenzar, asegúrese de tener:

• Fipy instalado y funcionando (ver Instalación y configuración de Fipy por primera vez para obtener la guía de instalación)
• Experiencia de programación de Python con fipy (familiaridad con es esencial los conceptos centrales de fipy)
• Un segundo solucionador Listo para el acoplamiento (este tutorial utiliza un simple solucionador de Python como suplente, pero el mismo patrón funciona con OpenFoam, Calculix u otros códigos habilitados para Precice)
• Precisión instalada en su sistema (ver Guía de instalación de Precice)
• Comprensión básica de la multifísica (revise ¿Qué es la simulación científica y por qué es importante? necesario)

Paso 1: Instalar enlaces de Python de Precice

Precice proporciona enlaces de Python, por lo que Fipy (o cualquier código de Python) puede actuar como un cliente de acoplamiento.

# Using conda (recommended)
conda install -c conda-forge precice

# Or using pip
pip install precice

Verifique la instalación:

python -c "import precice; print('preCICE Python version:', precice.__version__)"

Debería ver la versión de Precice impresa sin errores.

Paso 2: diseñe su interfaz de acoplamiento

Identifique donde interactúan los dos solucionadores. Escenarios comunes:

• Dominio Fipy → Campo de temperatura
• Otros Dominio de Solver → Flujo de calor o temperatura

Definir:

• Malla de interfaz en cada lado (puede ser diferente)
• datos de acoplamiento: qué cantidades se intercambian (por ejemplo, Temperature, Heat-Flux)
• Escalado de malla: Asegurar la alineación de los sistemas

Para este tutorial, combinaremos un solucionador de difusión de calor de Fipy con un solucionador de enfriamiento convectivo simple de Python. La interfaz es una línea 1D donde se intercambian temperatura y flujo de calor.

Paso 3: Escriba el adaptador Fipy Precice

El adaptador es el código que conecta su solucionador (fipy) a precice. Maneja:

• Inicialización de la conexión de precisión
• Definición de la malla de la interfaz de acoplamiento
• Lectura de datos entrantes del otro solucionador
• Escribir datos salientes para enviar
• Avanzar el paso del tiempo de acoplamiento

Crear un archivo fipy_precice_adapter.py:

import numpy as np
from fipy import CellVariable, Grid1D, DiffusionTerm, TransientTerm
import precice

# --- Configuration ---
# These should match the preCICE configuration file
COUPLING_INTERFACE = "Fluid-Solid"  # Name of the coupling interface
COUPLING_MESH_ID = 0  # ID of the mesh on this solver side
COUPLING_DATA_TEMPERATURE_ID = 0
COUPLING_DATA_HEATFLUX_ID = 1

# Simulation parameters
nx = 50
dx = 1.0
total_time = 10.0
dt = 0.1

# --- FiPy setup ---
mesh = Grid1D(nx=nx, dx=dx)
T = CellVariable(name="Temperature", mesh=mesh, value=300.0)  # Initial temp in K
k = 1.0  # Thermal conductivity

# Boundary conditions
# Left boundary: fixed temperature (will be overwritten by coupling)
# Right boundary: fixed temperature (example)
T.constrain(300.0, mesh.facesRight)

# Equation: transient diffusion
eq = TransientTerm() == DiffusionTerm(coeff=k)

# --- preCICE setup ---
solver_name = "FiPy-Solver"
config_file = "precice-config.xml"  # Provided separately

precice_dll = precice.Participant(solver_name, config_file, 0, 0)

# Get the coupling mesh from preCICE
mesh_vertices = precice_dll.get_mesh_vertices(COUPLING_MESH_ID, COUPLING_INTERFACE)
# In 1D, mesh_vertices is an array of x-coordinates
# We'll map these to our FiPy mesh cells

# Main coupling loop
time = 0.0
while time < total_time:
    # 1. Advance FiPy one time step (without coupling first)
    eq.solve(var=T, dt=dt)
    
    # 2. Read incoming data from the other solver (e.g., heat flux)
    # preCICE expects data at the coupling interface vertices
    heat_flux_in = precice_dll.read_data(
        COUPLING_DATA_HEATFLUX_ID,
        COUPLING_INTERFACE,
        mesh_vertices
    )
    
    # 3. Apply received heat flux as Neumann boundary condition on FiPy
    # This is simplified: in practice you'd map heat_flux_in to FiPy faces
    # For 1D, we can directly apply to left boundary
    if len(heat_flux_in) > 0:
        # Neumann BC: -k * dT/dx = heat_flux
        # In FiPy, you can set flux via constrained faces
        # For simplicity, we'll adjust the left boundary value to mimic flux
        # A proper implementation would use a FluxBoundaryCondition
        pass  # Implementation depends on exact boundary treatment
    
    # 4. Write outgoing data (temperature) to send to the other solver
    # Extract temperature at coupling interface cells
    T_interface = T.value  # In practice, sample at interface mesh locations
    precice_dll.write_data(
        COUPLING_DATA_TEMPERATURE_ID,
        COUPLING_INTERFACE,
        T_interface[:len(mesh_vertices)]  # ensure matching size
    )
    
    # 5. Advance coupling
    precice_dll.advance(dt)
    
    time += dt
    print(f"Time: {time:.2f}, Max T: {T.max():.2f}, Min T: {T.min():.2f}")

precice_dll.finalize()

Notas importantes:

• Este es un ejemplo mínimo. Las implementaciones reales necesitan una asignación de malla adecuada y una aplicación de condiciones de contorno.
• El archivo precice-config.xml define los ajustes de comunicación, los ID de malla y los ID de datos. Ver paso 4.
• Se simplifica la actualización de la condición de contorno de Fipy; Para el uso de la producción, implemente Neumann BC adecuado a través de FaceVariable o restricción personalizada.

Paso 4: Crear el archivo de configuración de Precice

Precice utiliza un archivo de configuración XML (precice-config.xml) que define:

• Participantes (Solucionadores)
• Interfaces de acoplamiento
• Definiciones de mallas y datos
• Configuración de comunicación
• Esquema de acoplamiento (explícito, implícito, cuasi-newton)

Una configuración mínima para el acoplamiento Fipy + Python Solver:

<?xml version="1.0" encoding="UTF-8"?>
<precice-configuration>
  <schema>https://precice.org/schemas/coupling-schema-2.2.xsd</schema>

  <!-- Parallel settings -->
  <parallel>
    <exchange comm-world="true" />
  </parallel>

  <!-- Coupling participants -->
  <participants>
    <participant name="FiPy-Solver">
      <use-mesh name="Fluid-Solid-Mesh-FiPy" provide="true" />
      <use-data name="Temperature" from="FiPy-Solver" />
      <use-data name="Heat-Flux" to="FiPy-Solver" />
    </participant>
    <participant name="SimpleSolver">
      <use-mesh name="Fluid-Solid-Mesh-Simple" provide="true" />
      <use-data name="Temperature" to="SimpleSolver" />
      <use-data name="Heat-Flux" from="SimpleSolver" />
    </participant>
  </participants>

  <!-- Coupling interfaces -->
  <coupling-scheme:serial-explicit>
    <participants first="FiPy-Solver" second="SimpleSolver" />
    <exchange>
      <data name="Temperature" mesh="Fluid-Solid-Mesh-FiPy" />
      <data name="Heat-Flux" mesh="Fluid-Solid-Mesh-Simple" />
    </exchange>
    <max-time>10.0</max-time>
    <max-iterations>10</max-iterations>
  </coupling-scheme:serial-explicit>

  <!-- Meshes -->
  <mesh name="Fluid-Solid-Mesh-FiPy" from="FiPy-Solver" />
  <mesh name="Fluid-Solid-Mesh-Simple" from="SimpleSolver" />

  <!-- Data -->
  <data name="Temperature" mesh="Fluid-Solid-Mesh-FiPy" />
  <data name="Heat-Flux" mesh="Fluid-Solid-Mesh-Simple" />

</precice-configuration>

Elementos clave:

• Dos participantes: FiPy-Solver y SimpleSolver
• Intercambio de datos: Temperature (fipy → simplesolver) y Heat-Flux (simplesolver → fipy)
• serial-explicit Acoplamiento: paso de tiempo explícito simple (bueno para comenzar)
• max-iterations Controla cuántas subiteraciones por paso de tiempo (para esquemas implícitos)

Para un acoplamiento más avanzado, considere:

• serial-implicit con aceleración cuasi-newton para acoplamiento más ajustado
• Factores de baja relajación para mejorar la convergencia
• Definiciones de conectividad de malla si las mallas no se alinean

Paso 5: Implemente el segundo solucionador (ejemplo simple)

Para probar el acoplamiento, necesitas un segundo solucionador. Aquí hay un solucionador de Python mínimo que intercambia flujo de calor con Fipy:

solver_simple.py:

import numpy as np
import precice

# Configuration
COUPLING_INTERFACE = "Fluid-Solid"
COUPLING_MESH_ID = 0
COUPLING_DATA_TEMPERATURE_ID = 0
COUPLING_DATA_HEATFLUX_ID = 1

solver_name = "SimpleSolver"
config_file = "precice-config.xml"

precice_dll = precice.Participant(solver_name, config_file, 0, 0)

# Simple 1D mesh (could be completely different from FiPy's mesh)
mesh_vertices = np.array([[0.0], [1.0]])  # Two points at interface
T_interface = np.array([300.0, 300.0])    # Initial guess

total_time = 10.0
dt = 0.1
time = 0.0

while time < total_time:
    # 1. Read incoming temperature from FiPy
    T_from_fipy = precice_dll.read_data(
        COUPLING_DATA_TEMPERATURE_ID,
        COUPLING_INTERFACE,
        mesh_vertices
    )
    
    # 2. Compute outgoing heat flux (simple Newton's law of cooling)
    # q = h * (T_fluid - T_solid)
    h = 10.0  # Heat transfer coefficient
    T_fluid = 350.0  # Ambient fluid temperature
    heat_flux = h * (T_fluid - T_from_fipy.mean())
    
    # Send same flux to all interface vertices (simplified)
    heat_flux_out = np.full_like(T_from_fipy, heat_flux)
    
    # 3. Write heat flux to send to FiPy
    precice_dll.write_data(
        COUPLING_DATA_HEATFLUX_ID,
        COUPLING_INTERFACE,
        heat_flux_out
    )
    
    # 4. Advance coupling
    precice_dll.advance(dt)
    
    time += dt
    print(f"[SimpleSolver] Time: {time:.2f}, T_fipy: {T_from_fipy.mean():.2f}, q: {heat_flux:.2f}")

precice_dll.finalize()

Este simple solucionador representa un entorno de enfriamiento convectivo que aplica un flujo de calor proporcional a la diferencia de temperatura con respecto al sólido fipy.

Paso 6: Ejecute la simulación acoplada

1. Inicie ambos solucionadores simultáneamente (precice administra su comunicación):

# Terminal 1
python fipy_precice_adapter.py &

# Terminal 2
python solver_simple.py &

2. Mira la salida. Debería ver el avance del tiempo tanto en los solucionadores como en los valores de temperatura/flujo de calor.
3. La simulación finaliza cuando se alcanza total_time o se completa el esquema de acoplamiento.

Comportamiento esperado:

• La temperatura de Fipy debería disminuir gradualmente desde los 300 K iniciales hacia la curva de enfriamiento
• El flujo de calor de SimpleSolver debe ser positivo (calor que deja FIPY)
• Ambos solucionadores deben permanecer sincronizados en el tiempo

Paso 7: Visualiza los resultados

Después de ejecutar, puedes trazar el perfil de temperatura de Fipy:

import matplotlib.pyplot as plt
from fipy import Grid1D, CellVariable, DiffusionTerm

# Re-run simulation while storing history
# (or modify the adapter to save snapshots to file)
# Then plot T vs x at final time

Solución de problemas: problemas y soluciones comunes

Consejos de depuración:

• Ejecute solucionadores con PRECICE_DEBUG=1 variable de entorno para registros detallados
• Comience con una malla gruesa y un tiempo total corto para probar rápidamente
• Use serial-explicit acoplamiento primero (el más indulgente) antes de probar esquemas implícitos
• Valide primero cada solucionador sin acoplar para asegurarse de que funcionen de forma independiente

Temas avanzados

Una vez que el acoplamiento básico funcione, explore:

Acoplamiento implícito con cuasi-newton

Para problemas estrechamente acoplados, los esquemas explícitos pueden requerir muchas subiteraciones o volverse inestables. Precice soporta acoplamiento implícito con aceleración cuasi-newton:

<coupling-scheme:serial-implicit>
  <participants first="FiPy-Solver" second="SimpleSolver" />
  <exchange>
    <data name="Temperature" mesh="Fluid-Solid-Mesh-FiPy" />
    <data name="Heat-Flux" mesh="Fluid-Solid-Mesh-Simple" />
  </exchange>
  <max-time>10.0</max-time>
  <max-iterations>10</max-iterations>
  <convergence-measure>
    <data name="Temperature" mesh="Fluid-Solid-Mesh-FiPy" />
  </convergence-measure>
  <relaxation value="0.5"/>
</coupling-scheme:serial-implicit>

Mapeo de malla a malla

Si la malla de interfaz de Fipy no coincide con la malla del otro solucionador, Precice realiza mapeo de malla (interpolación). Puede configurar el método de mapeo en XML:

<mesh name="Fluid-Solid-Mesh-FiPy" from="FiPy-Solver">
  <use-data name="Temperature" />
  <mapping:nearest-neighbor />
</mesh>

Opciones: nearest-neighbor, linear, rbf (Funciones de base radial). Elija en función de la calidad de la malla y la física.

Manejo de pasos de tiempo no coincidentes

Precice permite a cada solucionador utilizar su propio paso de tiempo mientras se coordina en las interfaces de acoplamiento. Establecer dt de forma independiente en cada solucionador; Precice interpolará los datos según sea necesario. Sin embargo, las grandes diferencias pueden reducir la precisión.

Consideraciones de rendimiento

• Sobrecarga de comunicación puede dominar para pequeños problemas. Perfil para asegurar que el acoplamiento no es el cuello de botella.
• Bajo-relajación (<relaxation> en XML) mejora la estabilidad pero ralentiza la convergencia.
• Resolución de malla en la interfaz afecta la precisión del mapeo. Use mallas de interfaz suficientemente refinadas.
• Escalado paralelo: Precice funciona con solucionadores habilitados para MPI. Asegúrese de que tanto FIPY (con PETSC) como el otro solucionador funcionen en paralelo si es necesario.

Próximos pasos

Después de dominar el acoplamiento básico:

1. Pruebe un segundo solucionador real (por ejemplo, OpenFoam para el flujo de fluido) en lugar del marcador de posición de Python
2. Explorar esquemas de acoplamiento avanzados (serial-implicit, multi)
3. Agregar más física (por ejemplo, unir tres solucionadores: térmico, fluido, estructural)
4. Implementar las condiciones de contorno adecuadas en fipy usando FaceVariable o términos personalizados
5. Optimizar el rendimiento con ejecución y perfiles paralelos
6. Estudios de casos de estudio como el acoplamiento termal-líquido o la interacción fluido-estructura

Para obtener un conocimiento más profundo, revise De las ecuaciones a las simulaciones: la canalización de modelado y método de volumen finito explicado simplemente.

Lectura adicional

• ¿Qué es Fipy y cuándo deberías usarlo? – Fundamentos y casos de uso de Fipy
• Instalación y configuración de Fipy por primera vez – Configuración del entorno y solución de problemas
• Qué es la simulación científica y por qué es importante – Metodología de simulación y mejores prácticas
• Desde ecuaciones a simulaciones: la canalización de modelado – Flujo de trabajo de extremo a extremo De ecuaciones a Resultados validados
• método de volumen finito explicado simplemente – método numérico central detrás de fipy
• comprender los modelos de campo de fase en la ciencia de los materiales – Aplicaciones de campo de fase de múltiples físicas
• Por qué el seguimiento de problemas es fundamental en proyectos científicos – Prácticas de reproducibilidad y colaboración

¿Necesita ayuda con su proyecto multifísico?

La creación de simulaciones acopladas sólidas requiere una profunda experiencia tanto en métodos numéricos como en la integración de software. Si está abordando un problema multifísico complejo y necesita orientación sobre:

• Diseño de un flujo de trabajo de acoplamiento con Precice
• Implementación de adaptadores fipy para su física específica
• Depuración de problemas de convergencia
• Optimización del rendimiento para simulaciones a gran escala

Matforge ofrece servicios de consulta para los flujos de trabajo de software de investigación. Podemos ayudarlo a configurar simulaciones multifísicas confiables y reproducibles adaptadas a su proyecto. Visite la página de inicio de Matforge para obtener más información y discutir sus necesidades específicas.

Resumen

• Precice permite el acoplamiento multifísico particionado, lo que permite que Fipy funcione con otros solucionadores
• Enfoque particionado es práctico para la investigación: reutilizar los códigos existentes, mantener la flexibilidad
• Pasos clave: Instalar Precice, Write Adapter, Configurar XML, Implementar intercambio de datos de límites
• Inicio simple: acoplamiento explícito con un ejemplo mínimo, luego progrese a esquemas implícitos
• validar primero cada solucionador independiente, luego juntos
• Monitor Convergencia y uso de baja relajación si es necesario

Con esta base, puede extender Fipy a prácticamente cualquier escenario multifísico.