Software Interfaces Are Two‑Way Contracts

Software Interfaces Are Two‑Way Contracts

When many engineers hear "interface," they think only about what a component offers to the outside world: the methods you can call, the events it can handle, the data it returns. But that's only half of the story.

Every software element also has expectations about its environment. It needs certain data, other components, and system conditions to be present and behaving in a particular way. If those expectations are not met, the element fails, even if all its public methods are implemented "correctly."

This is why a good way to think about an interface is:

An interface is a two‑way contract : what a component provides , and what it requires to function correctly.

---

Provided vs. Required Side of an Interface

You can split any interface into two parts:

• Provided side

  What the element offers to others.

  • Public functions / methods (run(), exportResults())
  • Events it can process (GUI clicks, callbacks, messages)
  • Data it returns (results, status, logs)

• Required side

  What the element expects from its environment.

  • Pre‑conditions on inputs (formats, ranges, completeness)
  • Behavior of other components (APIs, protocols, versions)
  • Properties of the runtime environment (OS, memory, licenses, network)

Ignoring the required side is like signing a contract but only reading what you promise, not what the other party must do.

---

In a CAE Context

As a CAE application engineer, you see this every day:

• A solver:

  • Provides: runAnalysis(model, settings), progress output, result files.
  • Requires:
    • Mesh quality criteria (no inverted elements, aspect ratio limits).
    • Materials and boundary conditions defined for all parts.
    • Enough memory, correct floating‑point behavior.
    • Valid license.

• A pre/post‑processor:

  • Provides: geometry/mesh editing, load/BC definition, visualization.
  • Requires:
    • Input files of known formats and units.
    • Solver output in a specific file format and directory layout.
    • Certain version compatibility with the solver.

If the solver quietly changes its result file format, the pre/post‑processor's required part of the interface is broken, and the workflow fails---even though its own provided functions have not changed.

For robust systems, you should:

• Design and document both what your component does and what it expects.
• Validate those expectations early (e.g., input checks, environment checks).
• Fail clearly when requirements are not satisfied.

---

Example 1 -- C++ Solver Interface (CAE‑like)

This example shows a simple solver class. The provided side is its public methods. The required side is expressed as checks and assumptions on the inputs.

// mesh.h
#pragma once
#include <vector>

struct Element {
    int id;
    double quality; // 0.0 (bad) to 1.0 (excellent)
};

class Mesh {
public:
    Mesh(std::vector<Element> elements) : elements_(std::move(elements)) {}

    bool isValid() const {
        if (elements_.empty()) return false;
        for (const auto& e : elements_) {
            if (e.quality < 0.5) {
                return false; // requirement: minimum element quality
            }
        }
        return true;
    }

    const std::vector<Element>& elements() const { return elements_; }

private:
    std::vector<Element> elements_;
};

// solver.h
#pragma once
#include "mesh.h"
#include <stdexcept>
#include <string>

struct SolverSettings {
    int maxIterations;
    double tolerance;
};

class Solver {
public:
    // PROVIDED: public interface
    Solver(std::string name) : name_(std::move(name)) {}

    void run(const Mesh& mesh, const SolverSettings& settings) {
        // REQUIRED: preconditions on environment and inputs
        if (!mesh.isValid()) {
            throw std::runtime_error("Solver requirement failed: invalid mesh.");
        }
        if (settings.maxIterations <= 0) {
            throw std::runtime_error("Solver requirement failed: maxIterations > 0.");
        }
        if (settings.tolerance <= 0.0 || settings.tolerance >= 1.0) {
            throw std::runtime_error("Solver requirement failed: 0 < tolerance < 1.");
        }

        // (In real life, you might also check: license, memory, etc.)

        // Implementation details hidden behind the interface
        doSolve(mesh, settings);
    }

private:
    void doSolve(const Mesh& mesh, const SolverSettings& settings) {
        // Fake solving logic
        // ... iterate over mesh.elements(), assemble matrices, etc.
    }

    std::string name_;
};

// main.cpp
#include "solver.h"
#include <iostream>

int main() {
    std::vector<Element> elems = {
        {1, 0.8},
        {2, 0.9}
    };
    Mesh mesh(elems);

    SolverSettings settings{1000, 1e-6};
    Solver solver("MyLinearSolver");

    try {
        solver.run(mesh, settings);  // uses PROVIDED interface
        std::cout << "Solve completed successfully.\n";
    } catch (const std::exception& ex) {
        std::cerr << "Solver failed: " << ex.what() << "\n";
    }
}

• Provided side : Solver::run(mesh, settings) is the visible entry point.
• Required side :
  • mesh.isValid() must be true (mesh quality requirement).
  • maxIterations > 0, 0 < tolerance < 1.
  • (Potentially) environment conditions like licenses and memory.

The requirements are part of the interface, even though they are "only" checks in code.

---

Example 2 -- Python Post‑Processor with File and Environment Requirements

Here we model a small post‑processor for solver results. It provides a simple function to load results, but it requires that:

• A results file exists at a given path.
• The file has specific columns.
• The units and solver version are supported.
• An environment variable is set for a default results directory.

# postprocessor.py
import os
import json
from pathlib import Path

class ResultLoadError(Exception):
    pass

class ResultPostProcessor:
    def __init__(self, solver_name: str):
        self.solver_name = solver_name

    # PROVIDED: public interface
    def load_results(self, case_name: str) -> dict:
        """
        Load results for a given case.

        Provided: returns a dictionary with result data.
        Required:
          - ENV var CAE_RESULTS_DIR must be set.
          - results JSON file must exist: {CAE_RESULTS_DIR}/{case_name}.json
          - JSON structure must contain 'displacements' and 'stresses'.
        """
        results_dir = self._get_results_dir()
        result_file = results_dir / f"{case_name}.json"

        if not result_file.exists():
            raise ResultLoadError(
                f"Requirement failed: results file {result_file} does not exist."
            )

        with result_file.open("r", encoding="utf-8") as f:
            data = json.load(f)

        # Required keys in the file
        required_keys = ["displacements", "stresses", "metadata"]
        for key in required_keys:
            if key not in data:
                raise ResultLoadError(
                    f"Requirement failed: key '{key}' missing in result file."
                )

        # Optional additional requirement on solver version
        metadata = data["metadata"]
        version = metadata.get("solver_version", "unknown")
        if version.startswith("0."):
            raise ResultLoadError(
                f"Requirement failed: unsupported solver version '{version}'."
            )

        return data

    # REQUIRED: environment expectation encapsulated in a helper
    def _get_results_dir(self) -> Path:
        env = os.getenv("CAE_RESULTS_DIR")
        if not env:
            raise ResultLoadError(
                "Requirement failed: CAE_RESULTS_DIR environment variable is not set."
            )
        path = Path(env)
        if not path.is_dir():
            raise ResultLoadError(
                f"Requirement failed: {path} is not a valid directory."
            )
        return path

# example_usage.py
import os
from postprocessor import ResultPostProcessor, ResultLoadError

# Simulate environment setup
os.environ["CAE_RESULTS_DIR"] = r"C:\temp\cae_results"

pp = ResultPostProcessor("MyNonlinearSolver")

try:
    results = pp.load_results("case123")  # PROVIDED interface
    print("Displacements:", results["displacements"][:5])
    print("Stresses:", results["stresses"][:5])
except ResultLoadError as e:
    print("Post-processing failed due to unmet requirement:", e)

• Provided side : load_results(case_name) -- the single call a user of this component makes.
• Required side :
  • CAE_RESULTS_DIR is set and points to a valid directory.
  • {case_name}.json exists.
  • File has required keys and supported solver version.

Again, those requirements are part of the interface, not just internal details.

---

How to Apply This in Your Own Work

When you design or review a component (a solver wrapper, pre/post‑processor module, licensing helper, etc.):

• Write down:
  • Provides: public functions/events/data.
  • Requires: inputs, other components, files, environment conditions.
• Enforce requirements with:
  • Input validation (parameter checks, file existence/format checks).
  • Clear error messages that say which requirement failed.
• Treat changes to requirements as interface changes, just like adding/removing functions.

If you'd like, tell me one of your real CAE workflows (tool names, typical data flow), and I can help you draft a concrete "Provided vs. Required" interface sketch for it.