Nvidia Modulus Symbolic(Modulus Sym) Workflow and Example

A typical workflow followed when developing in Modulus Sym.

Hydra

This is a configuration package designed to empower users in configuring hyperparameters. These hyperparameters determine the structure and training behavior of neural networks. Users can conveniently set these hyperparameters using YAML configuration files, a human-readable text format. Hydra plays the role of the first component initiated when addressing a problem with Modulus Sym. It wields influence across all aspects of Modulus Sym.

Geometry and Data 

Modulus Sym offers a dual approach for solving physics simulation challenges – a blend of physics-based knowledge and data-driven machine learning. Both these approaches revolve around transforming the physics problem into a mathematical optimization puzzle. The core of this problem exists within a specific geometry and dataset. Modulus Sym provides a flexible geometry module, allowing users to either create a new geometry from scratch using basic shapes or import existing geometries from mesh. In scenarios involving data-driven solutions, Modulus Sym offers diverse ways to access data, including standard in-memory datasets and resource-efficient lazy-loading methods for handling extensive datasets.

Nodes

Within Modulus Sym, Nodes play a key role by representing components executed during the forward pass of training. A Node encapsulates a torch.nn.Module, providing  input and output details. This attribute enables Modulus Sym to construct execution graphs and automatically fill in missing elements, essential for computing necessary derivatives. Nodes can encompass various elements, such as PyTorch neural networks natively integrated into Modulus Sym, user-defined PyTorch networks, feature transformations, and even equations.

Domain

The Domain is a central role by encompassing not only all the Constraints but also supplementary elements essential for the training journey. These supplementary components consist of Inferencers, Validators, and Monitors. As developers engage with Modulus Sym, the Constraints defined by the user are seamlessly integrated into the training Domain. This combinated results in the formation of a comprehensive assembly of training objectives, laying the foundation for a cohesive and purposeful training process.

Constraints

Constraints serve as the training goals. Each Constraint encompasses the loss function and a collection of Nodes, which Modulus Sym utilizes to construct a computational graph for execution. Numerous physical challenges require multiple training objectives to comprehensively define the problem. Constraints play a pivotal role in structuring such scenarios, offering the mechanism to establish these intricate problem setups.

Inferencers

An Inferencer primarily performs the forward pass of a set of Nodes. During training, Inferencers can be employed to evaluate training metrics or obtain predictions for visualization or deployment purposes. The frequency at which Inferencers are invoked is governed by Hydra configuration settings.

Validators

Validators function similarly to Inferencers but also incorporate validation data. Their role involves quantifying the model's accuracy during training by comparing it against physical outcomes generated through alternative methods. This "validation" phase verifies whether Modulus Sym meets operational requirements by comparing its computed simulation results to established known result.

Monitors

Monitors function similarly to Inferencers but also calculate specific measures instead of fields. These measures may encompass global quantities like total energy or local measurements like pressure in front of a bluff body (a distinctive shape with unique fluid dynamics attributes). Monitors are seamlessly integrated into Tensorboard results for easy visualization. Furthermore, Monitor outcomes can be exported to a text file in comma-separated values (CSV) format.

Solver

A Solver stands as a core component within Modulus Sym, responsible for implementing the optimization loop and overseeing the training process. By taking a predefined Domain, the Solver orchestrates the execution of Constraints, Inferencers, Validators, and Monitors as needed. In each iteration, the Solver calculates the overall loss from all Constraints and then refines any trainable models within the Nodes associated with the Constraints.

Modulus Sym Development Workflow

The key steps of general workflow include:

• "Load Hydra": Initialize Hydra using the Modulus Sym main decorator to read in the YAML configuration file.

• "Load Datasets": Load data if needed.

• "Define Geometry": Define the geometry of the system if needed.

• "Create Nodes": Create any Nodes required, such as the neural network model.

• "Create Domain": Create a training Domain object.

• "Create Constraint" and "Add Constraint to Domain"

• "Create {Validator, Inferencer, Monitor}" and "Add {Validator, Inferencer, Monitor} to Domain": Create any Inferencers, Validators or Monitors needed, and add them to the Domain.

• "Create Solver": Initialize a Solver with the populated training Domain.

• "Run Solver": Run the Solver. The resulting training process optimizes the neural network to solve the physics problem.

Modulus Training

• Modulus enables the representation of complex problems using sets of constraints, serving as training objectives.
• In constraints, the integration of multiple nodes or models allows for the acquisition of diverse loss functions—ranging from data-driven to physics-driven in nature.
• Seamlessly exporting the outcomes of trained models to visualization software becomes effortlessly achievable with Modulus.

Example

In the following section, we will solve the "Fluid Flow", "Parameterized Problem" and "Inverse Problem" with same geometry condition. All the examples will be demonstrate under OAsis portal, the job specification would be 4 CPU cores, 8GB Memory, 1g.10gb GPU. The conda environment need to setup completed as this articale.

A 2D chip is placed inside a 2D channel. The flow enters the inlet (a parabolic profile is used with  𝑢𝑚𝑎𝑥=1.5 m/s ) and exits through the outlet which is a  0𝑃𝑎 . All the other walls are treated as no-slip. The kinematic viscosity  (𝜈) for the flow is  0.02 𝑚2/𝑠 and the density  (𝜌) is  1 𝑘𝑔/𝑚3 . The problem is shown in the figure below.

Fluid Flow Problem

The main objective of this problem is to correctly formulate the problem using PINNs. In order to achieve that, you will have to complete the following parts successfully:

1. Define the correct geometry for the problem
2. Set up the correct boundary conditions and equations
3. Create the neural network and solve the problem

A successful completion of the problem should result in distribution of flow variables as shown below. Also, you should aim to achieve a relative  𝐿2 error of less than 0.2 for all the variables w.r.t the given OpenFOAM solution.

The primary goal of this challengeproblem is to accurately frameunderstand the problemflow utilizingof modulus sym development with Physics-Informed Neural Networks (PINNs). To accomplish this, you need to effectively execute the following steps:

1. Establish the Accurate Geometry: Define the geometry that corresponds to the problem.
2. Configure Boundary Conditions and Equations:Equations: Set up the appropriate boundary conditions and equations governing the problem's behavior.
3. Develop the Neural Network and Solve:Solve: Create the neural network architecture and employ it to solve the problem.

After the execution of the chip_2d.py script, you should observe a flow variable distribution akin to the illustrated example below. Furthermore, your objective should be to attain a relative 𝐿2 error of less than 0.2 for all variables when compared to the provided OpenFOAM solution.

Create the directory structure as below:

chip_2d/

chip_2d.py

conf/

config.yaml

openfoam/

2D_chip_fluid0.csv (unzip 2D_chip_fluid0.tar.xz file)

config.yaml File (Ref: https://docs.nvidia.com/deeplearning/modulus/modulus-sym/user_guide/features/configuration.html)

Configs inIn Modulus SymSym, areit requiredis importance for configurations to followadhere to a commonuniform structurestructure, toguaranteeing ensurethe thatinclusion allof necessaryessential parameters are provided independentirrespective of the user explicitly providing them.input. This is doneachieved by specifyingoutlining the

modulus_default

 schema at the topcommencement of the defaults list inwithin everyeach configuration filefile. whichThis willpractice createestablishes the followingsubsequent configconfiguration structure:

config
 |
 | <General parameters>
 |
 |- arch
     | <Architecture parameters>
 |- training
     | <Training parameters>
 |- loss
     | <Loss parameters>
 |- optimizer
     | <Optimizer parameters>
 |- scheduler
     | <Scheduler parameters>
 |- profiler
     | <Profiler parameters>

Architecture

The architecture configconfiguration group holdscontains a listcollection of model configurations that canserve beas usedblueprints tofor creategenerating differentdiverse pre-built in neural networks present within Modulus Sym. WhileAlthough not requiredobligatory byfor the Modulus Sym solver, this parameter group allowsempowers you to fine-tune model architectures throughusing either the YAML config file or even the command line.

To initializeinitiate an architecture usingbased on the config,configuration, Modulus Sym providesoffers ana convenient  instantiate_arch()method, method that allows different architectures to be initialized easily. The following two examples initializefacilitating the sameeffortless neuralinitialization network.of various architectures.

TheFor more available architecturesarchitectures, please referconsult nvidiathe modulusNVIDIA document.Modulus documentation.

Training

The training config group contains parameters essential to the training process of the model. This is set by default with modulus_default, but many of the parameters contained in this group are often essential to modify.

The available parameters please refer nvidia modulus document.

Loss

The loss configconfiguration group in NVIDIA Modulus is usedutilized to selectchoose from a range of different loss aggregationsaggregation that aremethods supported by Modulus Sym. A loss aggregation isrefers to the methodtechnique usedemployed to combine the individual losses fromgenerated differentby constraints.various constraints in a simulation. Different methods can yieldlead to improved performance for somespecific problems.problem scenarios.

TheFor availablemore loss methods please refer nvidia modulus document.

Optimizer

The loss optimizer group containswithin theNVIDIA Modulus encompasses a selection of supported optimizers that can be usedemployed in Modulus SymSym. whichThis includescollection onescomprises thatoptimizers are builtintegrated into PyTorch asand wellthose asavailable from the Torch Optimizer package. 

The available optimizers please refer nvidia modulus document.

Scheduler

The scheduler optimizer group containsin theNVIDIA Modulus encompasses a variety of supported learning rate schedulers that can be usedeffectively inapplied within Modulus Sym. ByIf no specific scheduler is specified, the default behavior is to employ a "none" is specified for which a constant learning rate willthroughout bethe used.training process.

The available schedulers please refer nvidia modulus document.

Run Modes

In NVIDIA Modulus SymSym, hasthere are two differentdistinct run modes availabledesigned for training and evaluation:

• train: DefaultThis is the default run mode.mode Trainsand is used for training the neural network. In this mode, the network's parameters are updated using optimization algorithms to minimize the loss function. Training involves iterating through the dataset, calculating gradients, and adjusting the model's parameters accordingly to improve its performance on the task.

• eval: EvaluatesThis providedmode is used for evaluation purposes. It involves assessing the performance of the trained model using specific inferencers, monitorsmonitors, and validatorsvalidators. The evaluation is conducted using the lastlatest checkpoint saved trainingduring checkpoint.training. UsefulThis mode is particularly useful for conducting post-processing aftertasks once the training phase is complete.

 defaults:
     - modulus_default

 run_mode: 'eval'

chip_2d.py File

LetLet's usbegin start withby importing the requirednecessary packages. PayTake attentionnote toof the variousdifferent modules and packages that are being imported, especiallyparticularly thethose related to equations, geometrygeometry, and architectures.

For more build in equations, geometry and architectures, please refer Modulus Sym Equations, Modulus Sym Geometry and Architectures In Modulus Sym

import numpy as np
from sympy import Symbol, Eq

import modulus.sym
from modulus.sym.hydra import to_absolute_path, ModulusConfig, instantiate_arch
from modulus.sym.utils.io import csv_to_dict
from modulus.sym.solver import Solver
from modulus.sym.domain import Domain
from modulus.sym.geometry.primitives_2d import Rectangle, Line, Channel2D
from modulus.sym.utils.sympy.functions import parabola
from modulus.sym.eq.pdes.navier_stokes import NavierStokes
from modulus.sym.eq.pdes.basic import NormalDotVec
from modulus.sym.domain.constraint import (
    PointwiseBoundaryConstraint,
    PointwiseInteriorConstraint,
    IntegralBoundaryConstraint,
)

from modulus.sym.domain.validator import PointwiseValidator
from modulus.sym.key import Key
from modulus.sym.node import Node

Now,Next, proceed to define the Nodes for the computational graph, appropriateset PDEs,up the relevant partial differential equations (PDEs), simulation parametersparameters, and generate the geometry. YouFor willthis betask, usingutilize the NavierStokes class from the PDEs module forto imposingapply the necessary PDE constraints offor this specific problem.

@modulus.sym.main(config_path="conf", config_name="config")
def run(cfg: ModulusConfig) -> None:

    # make list of nodes to unroll graph on
    ns = NavierStokes(nu=0.02, rho=1.0, dim=2, time=False)
    normal_dot_vel = NormalDotVec(["u", "v"])
    flow_net = instantiate_arch(
        input_keys=[Key("x"), Key("y")],
        output_keys=[Key("u"), Key("v"), Key("p")],
        frequencies=("axis", [i / 2 for i in range(8)]),
        frequencies_params=("axis", [i / 2 for i in range(8)]),
        cfg=cfg.arch.fourier,
    )
    nodes = (
        ns.make_nodes()
        + normal_dot_vel.make_nodes()
        + [flow_net.make_node(name="flow_network", jit=cfg.jit)]
    )

Next,Moving forward, you will be usingemploy the 2D geometry modules for this example. Keep Remember,in mind that both the Channel2D and Rectangle geometries are defined by itsspecifying their two endpoints. TheIt's differenceworth noting that a key distinction between a channel and a rectangle in Modulus is that,that the channel geometry does not havelacks bounding curves in the x-direction. This isunique helpfulfeature inensures gettingthe creation of a signed distance field that isremains infinite in the x-direction. This canproperty bebecomes importantsignificant when utilizing the signed distance field is used as a wall distance in some of thespecific turbulence models (ReferFor more detailed information, refer to the Modulus User Documentation).

for

In morethis details).context, Hence, we willyou'll create the inlet and outlet using Line geometrygeometry. (PleaseIt's noteimportant to clarify that this is a 2d2D line, as opposed tounlike the Line1D that was used in the diffusion tutorial)tutorial.

AlsoFurthermore, take note of the geo_lr and geo_hr  as two separatedistinct geometries. These are introduced primarily constructed to varyenable thevariable sampling betweendensity across different areasregions of the geometry. The ideaconcept of havingadjusting differentthe sampling density for the points in different areas,areas allows usfor toincreased samplepoint moresampling points closer tonear the heatsinkheatsink, (where we expect a larger variation in the flow field).field Therevariations are multipleexpected. waysThis inapproach whichof this variablevarying sampling density can be achieved through multiple methods, and herein wethis takescenario, one of the simplest approach where weyou'll create two differentseparate geometry elements for the high resolution and low resolution.resolution purposes.

    # add constraints to solver
    # simulation params
    channel_length = (-2.5, 2.5)
    channel_width = (-0.5, 0.5)
    chip_pos = -1.0
    chip_height = 0.6
    chip_width = 1.0
    inlet_vel = 1.5

    # define sympy variables to parametrize domain curves
    x, y = Symbol("x"), Symbol("y")

    # define geometry
    channel = Channel2D(
        (channel_length[0], channel_width[0]), (channel_length[1], channel_width[1])
    )
    inlet = Line(
        (channel_length[0], channel_width[0]),
        (channel_length[0], channel_width[1]),
        normal=1,
    )
    outlet = Line(
        (channel_length[1], channel_width[0]),
        (channel_length[1], channel_width[1]),
        normal=1,
    )
    rec = Rectangle(
        (chip_pos, channel_width[0]),
        (chip_pos + chip_width, channel_width[0] + chip_height),
    )
    flow_rec = Rectangle(
        (chip_pos - 0.25, channel_width[0]),
        (chip_pos + chip_width + 0.25, channel_width[1]),
    )
    geo = channel - rec
    geo_hr = geo & flow_rec
    geo_lr = geo - flow_rec

The current problemscenario isinvolves a channel flow withfeaturing an incompressible fluid. In suchsituations cases,like these, it's important to note that the mass flow rate through each cross-section of the channelchannel, and in turnconsequently the volumetric flowflow, isremains constant. This characteristic can be usedserve as an additionalextra constraint in the problemproblem, whichcontributing willto helpenhanced usconvergence in improving the speed of convergence.speed.

Wherever,Whenever possible,feasible, using suchleveraging additional knowledgeinsights about the problem can helplead into bettermore efficient and fasterquicker solutions. MoreFor examplesfurther instances of thissuch practices, you can berefer found into the Modulus User Documentation.

    x_pos = Symbol("x_pos")
    integral_line = Line((x_pos, channel_width[0]), (x_pos, channel_width[1]), 1)
    x_pos_range = {
        x_pos: lambda batch_size: np.full(
            (batch_size, 1), np.random.uniform(channel_length[0], channel_length[1])
        )
    }

Now you will use the created geometry to define the training constraints for the problem. Implement the required boundary conditions and equations below. Remember that you will have to create constraints for both for the boundary condition and to reduce the equation residuals. You can refer to the NavierStokes class from the PDEs module to check how the equations are defined, and the keys required for each equation.

Now use this understanding to define the problem. An example of the inlet boundary condition is shown. Also, the integral continuity constraint is already coded up for you.

    # make domain
    domain = Domain()

    # inlet
    inlet_parabola = parabola(y, channel_width[0], channel_width[1], inlet_vel)
    inlet = PointwiseBoundaryConstraint(
        nodes=nodes,
        geometry=inlet,
        outvar={"u": inlet_parabola, "v": 0},
        batch_size=cfg.batch_size.inlet,
    )
    domain.add_constraint(inlet, "inlet")

    # outlet
    outlet = PointwiseBoundaryConstraint(
        nodes=nodes,
        geometry=outlet,
        outvar={"p": 0},
        batch_size=cfg.batch_size.outlet,
        criteria=Eq(x, channel_length[1]),
    )
    domain.add_constraint(outlet, "outlet")

    # no slip
    no_slip = PointwiseBoundaryConstraint(
        nodes=nodes,
        geometry=geo,
        outvar={"u": 0, "v": 0},
        batch_size=cfg.batch_size.no_slip,
    )
    domain.add_constraint(no_slip, "no_slip")

    # interior lr
    interior_lr = PointwiseInteriorConstraint(
        nodes=nodes,
        geometry=geo_lr,
        outvar={"continuity": 0, "momentum_x": 0, "momentum_y": 0},
        batch_size=cfg.batch_size.interior_lr,
        bounds={x: channel_length, y: channel_width},
        lambda_weighting={
            "continuity": 2 * Symbol("sdf"),
            "momentum_x": 2 * Symbol("sdf"),
            "momentum_y": 2 * Symbol("sdf"),
        },
    )
    domain.add_constraint(interior_lr, "interior_lr")

    # interior hr
    interior_hr = PointwiseInteriorConstraint(
        nodes=nodes,
        geometry=geo_hr,
        outvar={"continuity": 0, "momentum_x": 0, "momentum_y": 0},
        batch_size=cfg.batch_size.interior_hr,
        bounds={x: channel_length, y: channel_width},
        lambda_weighting={
            "continuity": 2 * Symbol("sdf"),
            "momentum_x": 2 * Symbol("sdf"),
            "momentum_y": 2 * Symbol("sdf"),
        },
    )
    domain.add_constraint(interior_hr, "interior_hr")

    # integral continuity
    def integral_criteria(invar, params):
        sdf = geo.sdf(invar, params)
        return np.greater(sdf["sdf"], 0)

    integral_continuity = IntegralBoundaryConstraint(
        nodes=nodes,
        geometry=integral_line,
        outvar={"normal_dot_vel": 1},
        batch_size=cfg.batch_size.num_integral_continuity,
        integral_batch_size=cfg.batch_size.integral_continuity,
        lambda_weighting={"normal_dot_vel": 1},
        criteria=integral_criteria,
        parameterization=x_pos_range,
    )
    domain.add_constraint(integral_continuity, "integral_continuity")

Now, add validation data to the problem. The openfoam directory that contains the solution of same problem using OpenFOAM solver. The CSV file is read in and converted to a dictionary for you. 

    # add validation data
    mapping = {"Points:0": "x", "Points:1": "y", "U:0": "u", "U:1": "v", "p": "p"}
    openfoam_var = csv_to_dict(to_absolute_path("openfoam/2D_chip_fluid0.csv"), mapping)
    openfoam_var["x"] -= 2.5  # normalize pos
    openfoam_var["y"] -= 0.5
    openfoam_invar_numpy = {
        key: value for key, value in openfoam_var.items() if key in ["x", "y"]
    }
    openfoam_outvar_numpy = {
        key: value for key, value in openfoam_var.items() if key in ["u", "v", "p"]
    }
    openfoam_validator = PointwiseValidator(
        invar=openfoam_invar_numpy, true_outvar=openfoam_outvar_numpy, nodes=nodes
    )
    domain.add_validator(openfoam_validator)

Now, complete the last part of the code by creating the Solver to solve the problem. The important hyperparameters of the problem are defined for you in the config file. Feel free to tweak them and observe its behavior on the results and speed of convergence.

    # make solver
    slv = Solver(cfg, domain)

    # start solver
    slv.solve()

if __name__ == "__main__":
    run()

You can execute it by "python chip_2d.py". Record your relative L2 errors with respect to the OpenFOAM solution and try to achieve errors for all the variables lower than 0.2. Download and Open the  .npz file with ParaView software created in the network checkpoint. 

select the .npz file

Press "Apply"

you can change to view different predicted graphic

compare the difference between true value and predicted values.