Getting started#

You can use gRPC to drive your Fluent simulations from any language that supports gRPC. A suite of neatly segregated services allows you to perform meshing, solver setup and execution, live monitoring, field-data extraction, and more.

Fluent’s gRPC server is built in — you only need to set up the client layer. Below, you’ll find the prerequisites for setting up your gRPC client, instructions for getting everything installed, and guidance on building and using your gRPC client code.

Getting the proto files#

The .proto files that define every Fluent gRPC service, method, and message are available in the ansys-api-fluent repository.

Prerequisites#

Before compiling the .proto files you need:

A Protocol Buffers compiler (protoc), at a version compatible with the repository’s .proto files.
A language-specific gRPC plug-in or toolchain:
- Python – grpcio-tools (pip install grpcio-tools), which bundles protoc and the Python plug-in.
- C++ – grpc_cpp_plugin and a C++ toolchain.
- Go – Go toolchain plus protoc-gen-go and protoc-gen-go-grpc.
- Java – JDK and the protoc-gen-grpc-java plug-in.
- C# – grpc_csharp_plugin, or the Grpc.Tools NuGet package for MSBuild integration.

Ensure protoc and any protoc-gen-* plug-ins are on PATH, or pass --plugin=protoc-gen-<lang>=<path> explicitly when invoking protoc.

Compiling proto files#

Clone the ansys-api-fluent repository, then run protoc with the appropriate gRPC plug-in against the files in ansys/api/fluent/v1/. To run these commands directly as they stand, the protoc executable and any protoc-gen-* plug-ins should be discoverable via the system path; alternatively, pass their locations explicitly with –plugin=protoc-gen-<lang>=<path>.

Note

Each command below compiles a single .proto file (health.proto is used here) against one language’s plug-in; repeat the invocation for each service, or pass multiple .proto files in one call, to generate stubs for the full API. The Python example uses the python -m grpc_tools.protoc wrapper, installed via pip install grpcio-tools, which bundles protoc and the Python plug-in together; the other languages require protoc and their plug-in to be installed and available separately, as described above.

pip install grpcio-tools
python -m grpc_tools.protoc \
    -I ansys/api/fluent/v1 \
    --python_out=<out> \
    --grpc_python_out=<out> \
    ansys/api/fluent/v1/health.proto

protoc \
    -I ansys/api/fluent/v1 \
    --cpp_out=<out> \
    --grpc_out=<out> \
    --plugin=protoc-gen-grpc=grpc_cpp_plugin \
    ansys/api/fluent/v1/health.proto

protoc \
    -I ansys/api/fluent/v1 \
    --go_out=<out> \
    --go_opt=Mhealth.proto=github.com/ansys/ansys-api-fluent/ansys/api/fluent/v1 \
    --go-grpc_out=<out> \
    --go-grpc_opt=Mhealth.proto=github.com/ansys/ansys-api-fluent/ansys/api/fluent/v1 \
    ansys/api/fluent/v1/health.proto

protoc \
    -I ansys/api/fluent/v1 \
    --java_out=<out> \
    --grpc-java_out=<out> \
    --plugin=protoc-gen-grpc-java=protoc-gen-grpc-java \
    ansys/api/fluent/v1/health.proto

protoc \
    -I ansys/api/fluent/v1 \
    --csharp_out=<out> \
    --grpc_out=<out> \
    --plugin=protoc-gen-grpc=grpc_csharp_plugin \
    ansys/api/fluent/v1/health.proto

Python package (Python 3.10+)#

Python stubs are pre-generated and published to PyPI, offering a ready-made alternative to compiling the proto files yourself. Install the package and import the generated modules directly:

pip install ansys-api-fluent

Making a service call#

The examples below fetch the health status from a running Fluent server. Before running them, ensure you have:

A running Fluent server (Ansys Fluent 27R1 or later)
Its address and password

Note

When Fluent starts its gRPC server, it writes the connection details to a server info file. Launch Fluent with the -sifile=<file> argument to specify where that file is written. The file contains two lines in order: the server address and the password. Read those values from the file and substitute them for <server-address> and <password> in the examples below.

The following snippets illustrate the common pattern across languages.

import grpc
from ansys.api.fluent.v1 import health_pb2, health_pb2_grpc

channel = grpc.insecure_channel("<server-address>")
stub = health_pb2_grpc.HealthStub(channel)
request = health_pb2.HealthCheckRequest()
response = stub.Check(
    request,
    metadata=[("password", "<password>")],
)
print(f"Status: {response.status}")
channel.close()

#include <iostream>
#include <grpcpp/grpcpp.h>
#include "health.grpc.pb.h"

int main() {
    auto channel = grpc::CreateChannel(
        "<server-address>", grpc::InsecureChannelCredentials());
    grpc::ClientContext ctx;
    ctx.AddMetadata("password", "<password>");
    auto stub = ansys::api::fluent::v1::Health::NewStub(channel);
    ansys::api::fluent::v1::HealthCheckRequest req;
    ansys::api::fluent::v1::HealthCheckResponse resp;
    stub->Check(&ctx, req, &resp);
    std::cout << "Status: " << resp.status() << std::endl;
}

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/metadata"
    pb "github.com/ansys/ansys-api-fluent/ansys/api/fluent/v1"
)

func main() {
    conn, _ := grpc.Dial("<server-address>",
        grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn.Close()
    ctx := metadata.AppendToOutgoingContext(
        context.Background(), "password", "<password>")
    resp, err := pb.NewHealthClient(conn).Check(ctx, &pb.HealthCheckRequest{})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Status: %v\n", resp.Status)
}

import io.grpc.*;
import io.grpc.stub.MetadataUtils;
import ansys.api.fluent.v1.*;

public class HealthCheck {
    public static void main(String[] args) {
        Metadata headers = new Metadata();
        headers.put(Metadata.Key.of("password",
            Metadata.ASCII_STRING_MARSHALLER), "<password>");
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("<server-address>").usePlaintext().build();
        HealthGrpc.HealthBlockingStub stub =
            MetadataUtils.attachHeaders(
                HealthGrpc.newBlockingStub(channel), headers);
        HealthCheckResponse resp =
            stub.check(HealthCheckRequest.newBuilder().build());
        System.out.println("Status: " + resp.getStatus());
        channel.shutdown();
    }
}

using Grpc.Core;
using Ansys.Api.Fluent.V1;

var channel = new Channel("<server-address>", ChannelCredentials.Insecure);
var headers = new Metadata { { "password", "<password>" } };
var client = new Health.HealthClient(channel);
var resp = client.Check(new HealthCheckRequest(),
    new CallOptions(headers: headers));
Console.WriteLine($"Status: {resp.Status}");
await channel.ShutdownAsync();