Appendices: JSON Schema and Compiler Syntax

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "description": "Swan Simulator JSON configuration file schema",
  "properties": {
      "root_operator": {
        "type": "string",
         "description": "Swan pathname of the simulation root operator within input Swan model"
      },
      "input_scenario_file": {
        "type": "string",
        "description": "Pathname of the test sequence file to be executed"
       },
      "cycles_count": {
        "type": "integer",
        "description": "Number of cycles to be executed"
       },
       "cycle_period": {
         "type": "integer",
         "description": "Cycle execution period, in µs, for pseudo real-time mode"
       },
       "float32_absolute_tolerance": {
         "type": "number",
         "description": "Absolute tolerance applied in float32 comparisons"
       },
       "float32_relative_tolerance": {
         "type": "number",
         "description": "Relative tolerance applied in float32 comparisons"
       },
       "float64_absolute_tolerance": {
         "type": "number",
          "description": "Absolute tolerance applied in float64 comparisons"
       },
       "float64_relative_tolerance": {
         "type": "number",
         "description": "Relative tolerance applied in float64 comparisons"
       },
       "output_trace_file": {
         "type": "string",
         "description": "Pathname of the execution trace file to be produced"
       },
       "output_test_results_file": {
         "type": "string",
         "description": "Pathname of the test results file to be produced"
       },
       "simulation_executable_file": {
         "type": "string",
         "description": "Pathname of the simulation execution file to be produced"
       },
       "compiler_mk_file": {
         "type": "string",
         "description": "Pathname to a file to be included when building simulation executable"
       },
       "make_command": {
         "type": "string",
         "description": "Pathname to a file (script) to be launched for building simulation executable"
       },
       "imported_type_header_files": {
         "type": "array", "items": { "type": "string" },
         "description": "Pathname to .h files containing declaration of imported types part of input Swan model"
       },
       "user_config_header_files": {
         "type": "array", "items": { "type": "string" },
         "description": "Pathname to .h files containing re-definition of C macros defined in |swan_cg| generated code"
       },
       "source_files": {
         "type": "array", "items": { "type": "string" },
         "description": "Pathname to .c files to be compiled and linked in simulation executable"
       },
       "include_dirs": {
         "type": "array", "items": { "type": "string" },
         "description": "Pathname to directories to be considered when building simulation executable"
       },
       "object_files": {
                    "type": "array", "items": { "type": "string" },
                    "description": "Pathname to .lib/.o/.obj/.a files to be linked in simulation executable"
       },
       "resource_files": {
         "type": "array", "items": {
         "type": "object",
         "properties": { "id": { "type": "string" }, "file": { "type": "string" }},
         "required": ["id", "file"]
         },
         "description": "Pathname to resource files that can be used by data source operators"
       },
       "keep_sim_dir": {
         "type": "boolean",
         "description": "Keep temporary directory on disk after execution"
       },
       "model_files": {
         "type": "array", "items": { "type": "string" },
         "description": "Pathname to input Swan model files"
       }
     },
     "required": ["root_operator", "model_files"],
     "additionalProperties": true
 }

The following schema is specified using JSON Schema, see details in https://json-schema.org/.

{
  "type": "object",
  "description": "Swan Simulator JSON log file schema",
  "properties": {
    "version": {
      "description": "Schema version of the log",
      "type": "string"
    },
    "log_entries": {
      "description": "List of log entries",
      "type": "array",
      "items": { "$ref": "#/$defs/LogEntry" }
    }
  },

  "$defs": {
    "LogEntry": {
      "type": "object",
      "description": "A log entry",
      "properties": {
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "Message timestamp (<YYYY>-<MM>-<DD>T<hh>:<mm>:<ss>Z)"
          },
        "tool": { "type": "string" },
        "severity": { "enum": ["INFO", "NOTICE"] },
        "message_kind": {
          "type": "string",
          "description": "A string value identifying the message template"
        },
        "message": {
          "type": "object",
          "description": "A JSON object corresponding to [message_kind]",
          "anyOf": [
              { "$ref": "#/$defs/GeneralInfo" },
              { "$ref": "#/$defs/SimOptions" },
              { "$ref": "#/$defs/Failure" },
              { "$ref": "#/$defs/Diagnostic" },
              { "$ref": "#/$defs/GeneratedFile" },
              { "$ref": "#/$defs/TentativeExitStatus" },
              { "$ref": "#/$defs/Success" }
          ]
        }
      },
      "required": ["timestamp", "tool", "severity", "message_kind", "message"]
    },

    "GeneralInfo": {
      "type": "object",
      "description": "Message giving general information on execution ([message_kind] = 'general_info')",
      "properties": {
          "tool_name": {
            "type": "string",
            "description": "Identification of the tool that produced the log file"
          },
          "tool_version": {
            "type": "string",
            "description": "Version of the tool"
          },
          "tool_executable": {
            "$ref" : "#/$defs/FileLocation",
            "description": "Full pathname of the tool"
          },
          "external_tools":  {
            "type": "array", "items": {"$ref" : "#/$defs/FileLocation"},
            "description": "Full pathname of external tools used"
          },
          "host": {
            "type": "string",
            "description": "Name of the computer executing the tool"
          },
          "working_dir": {
            "$ref" : "#/$defs/FileLocation",
            "description": "Working directory of the execution"
          },
          "command_line_arguments": {
            "type": "array", "items": {"type": "string"},
            "description": "Command line arguments"
          }
      },
      "required": ["tool_name", "tool_version"],
      "additionalProperties": true
    },

    "SimOptions": {
      "type": "object",
      "description": "Message recalling simulator input options ([message_kind] = 'sim_options')",
      "properties": {
        "root_operator": {
          "type": "string",
          "description": "Swan pathname of the simulation root operator within input Swan model"
        },
        "input_scenario_file": {
          "$ref" : "#/$defs/FileLocation",
          "description": "Pathname of the test sequence file to be executed"
          },
        "cycles_count": {
          "type": "integer",
          "description": "Number of cycles to be executed"
        },
        "cycle_period": {
          "type": "integer",
          "description": "Cycle execution period, in µs, for pseudo real-time mode"
        },
        "output_trace_file": {
          "$ref" : "#/$defs/FileLocation",
          "description": "Pathname of the execution trace file to be produced"
        },
        "simulation_executable_file": {
          "$ref" : "#/$defs/FileLocation",
          "description": "Pathname of the simulation execution file to be produced"
        },
        "compiler_mk_file": {
          "$ref" : "#/$defs/FileLocation",
          "description": "Pathname of a file to be included when building simulation executable"
        },
        "make_command": {
          "$ref" : "#/$defs/FileLocation",
          "description": "Pathname of a file (script) to be launched for building simulation executable"
        },
        "imported_type_header_files": {
          "type": "array", "items": {"$ref" : "#/$defs/FileLocation"},
          "description": "Pathname of .h files containing declaration of imported types part of input Swan model"
        },
        "user_config_header_files": {
          "type": "array", "items": {"$ref" : "#/$defs/FileLocation"},
          "description": "Pathname of .h files containing re-definition of C macros defined in |swan_cg| generated code"
        },
        "source_files": {
          "type": "array", "items": {"$ref" : "#/$defs/FileLocation"},
          "description": "Pathname of .c files to be compiled and linked in simulation executable"
        },
        "include_dirs": {
          "type": "array", "items": {"$ref" : "#/$defs/FileLocation"},
          "description": "Pathname of directories to be considered when building simulation executable"
        },
        "object_files": {
          "type": "array", "items": {"$ref" : "#/$defs/FileLocation"},
          "description": "Pathname of .lib/.o/.obj/.a files to be linked in simulation executable"
        },
        "resource_files": {
          "type": "array", "items": {
            "type": "object",
            "properties": {"id": { "type": "string" }, "file": { "$ref": "#/$defs/FileLocation" }},
            "required": ["id", "file"]
          },
          "description": "Pathname of resource files that can be used by data source operators"
        },
        "keep_sim_dir": {
          "type": "boolean",
          "description": "Keep temporary directory on disk after execution"
        },
        "model_files": {
          "type": "array", "items": {"$ref" : "#/$defs/FileLocation"},
          "description": "Pathname of input Swan model files"
        }
      },
      "required": ["root_operator", "model_files"],
      "additionalProperties": true
    },

    "GeneratedFile": {
      "type": "object",
      "description": "Message indicating that a file has been produced by execution ([message_kind] = 'generated_file')",
      "properties": {
        "ident": { "type": "string" , "description": "Kind of generated file"},
        "location": { "$ref" : "#/$defs/FileLocation", "description": "Pathname of generated file"}
      },
      "required": ["location"]
    },

    "TentativeExitStatus": {
      "type": "object",
      "description": "Message indicating tentative exit status of the tool ([message_kind] = 'tentative_exit_status')",
      "properties": {
        "value": {"type":"integer" , "description": "Tentative exit status value"}
      },
      "required": ["value"]
    },

    "Success": {
      "type": "object",
      "description": "Message indicating success of the execution ([message_kind] = 'success')",
      "properties": {
        "value": {"type":"boolean" , "description": "true is execution is successful"}
      },
      "required": ["value"]
    },

    "Failure": {
      "type": "object",
      "description": "Message indicating a failure during execution ([message_kind] = 'failure')",
      "properties": {
        "key": { "type": "string" },
        "template": {
          "type": "string",
          "description": "An informative message that may contain placeholder {{param}}"
        },
        "parameters": { "$ref" : "#/$defs/ParamsMap"}
      },
      "required": ["key", "template"]
    },

    "Diagnostic": {
      "type": "object",
      "description": "Message for diagnostics ([message_kind] = 'diagnostic')",
      "properties": {
        "key": { "type": "string" },
        "template": {
          "type": "string",
          "description": "An informative message that may contain placeholder {{param}}"
        },
        "parameters": { "$ref" : "#/$defs/ParamsMap" },
        "experimental": { "type" : "boolean" },
        "level": { "enum": ["ERROR", "WARNING", "INFO"] }
      },
      "required": ["key", "template", "level"]
    },

    "ParamsMap": {
      "type": "object",
      "description": "A list that maps the parameters used in the template to their actual values",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "array",
            "items": [
              { "const": "file_location" },
              { "$ref" : "#/$defs/FileLocation" }
            ]
          },
          {
            "type": "array",
            "items": [
              { "const": "raw" },
              { "type" : "string"}
            ]
          }
        ]
      }
    },

    "FileLocation": {
      "type": "object",
      "description": "Location of a file and optionally within this file",
      "properties": {
        "path": { "type": "string" },
        "range": {
          "type": "array",
          "items": { "type": "integer" }
        }
      },
      "required": ["path"]
    }
  }
}

Example of Log File complying with the JSON Schema Syntax:

{
  "version": "0.1",
  "log_entries": [
    {
      "timestamp": "2024-01-22T15:21:28Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "general_info",
      "message": {
        "tool_name": "Ansys Scade One - Swan Simulator",
        "tool_version": "2.0.0.051",
        "tool_executable": {
          "path": "C:\\Program Files\\Ansys Inc\\v241\\Scade One\\tools\\simulator\\swan_sim.exe"
        },
        "external_tools": [
          {
            "path": "C:\\Program Files\\Ansys Inc\\v241\\Scade One\\tools\\swan_cg.exe"
          },
          {
            "path": "C:\\Program Files\\Ansys Inc\\v241\\Scade One\\tools\\swan_cg.exe"
          },
          {
            "path": "C:\\Program Files\\Ansys Inc\\v241\\Scade One\\contrib\\mingw64"
          }
        ],
        "host": "AAP3ex77kUbiJya",
        "working_dir": {
          "path": "D:\\examples\\GettingStarted\\MyFirstModelWithSOne\\Initial\\Thermometer\\jobs\\simu_6a5c4bf"
        },
        "command_line_arguments": [
          "D:\\examples\\GettingStarted\\MyFirstModelWithSOne\\Initial\\Thermometer\\jobs\\simu_6a5c4bf\\config.json"
        ]
      }
    },
    {
      "timestamp": "2024-01-22T15:21:28Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "sim_options",
      "message": {
        "model_files": [
          {
            "path": "D:\\examples\\GettingStarted\\MyFirstModelWithSOne\\Initial\\Thermometer\\assets\\Thermometer.swan"
          },
          {
            "path": "D:\\examples\\GettingStarted\\MyFirstModelWithSOne\\Initial\\Thermometer\\assets\\TestModule.swant"
          }
        ],
        "root_operator": "TestModule::TestHarness",
        "output_trace_file": {
          "path": "D:\\examples\\GettingStarted\\MyFirstModelWithSOne\\Initial\\Thermometer\\jobs\\simu_6a5c4bf\\out\\trace.sd"
        }
      }
    },
    {
      "timestamp": "2024-01-22T15:21:30Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "diagnostic",
      "message": {
        "level": "INFO",
        "key": "sim.info.code_gen.done",
        "template": "code for model generated in {{ elapsed_ms }} ms",
        "parameters": {
          "elapsed_ms": [
            "raw",
            "1783"
          ]
        }
      }
    },
    {
      "timestamp": "2024-01-22T15:21:30Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "diagnostic",
      "message": {
        "level": "INFO",
        "key": "sim.info.wrap_gen.done",
        "template": "wrapping code generated in {{ elapsed_ms }} ms",
        "parameters": {
          "elapsed_ms": [
            "raw",
            "60"
          ]
        }
      }
    },
    {
      "timestamp": "2024-01-22T15:21:38Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "diagnostic",
      "message": {
        "level": "INFO",
        "key": "sim.info.build.done",
        "template": "simulation executable built in {{ elapsed_ms }} ms",
        "parameters": {
          "elapsed_ms": [
            "raw",
            "7478"
          ]
        }
      }
    },
    {
      "timestamp": "2024-01-22T15:21:49Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "generated_file",
      "message": {
        "ident": "Trace",
        "location": {
          "path": "D:\\examples\\GettingStarted\\MyFirstModelWithSOne\\Initial\\Thermometer\\jobs\\simu_6a5c4bf\\out\\trace.sd"
        }
      }
    },
    {
      "timestamp": "2024-01-22T15:21:49Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "tentative_exit_status",
      "message": {
        "value": 0
      }
    },
    {
      "timestamp": "2024-01-22T15:21:49Z",
      "tool": "SIMULATOR",
      "severity": "INFO",
      "message_kind": "success",
      "message": {
        "value": true
      }
    }
  ]
}

Compiler configuration files are files with .mk extension which define the variables below using the format <variable name> = <value>:

Variable Name	Description
SHELL	Shell executable
CC	C&C++ compiler executable
LD	Linker executable
PROTOC	Protobuf compiler executable
CFLAGS	Compiler flags
LDFLAGS	Linker flags
PPDEF	Option for specifying preprocessor definition to the compiler
CCINC	Option for specifying include directory to the compiler
CCOUT	Option for specifying output of compiler command
LDOUT	Option for specifying output of linker command

Example of content complying with the Compiler Configuration File Syntax:

SHELL = cmd.exe

CC = clang++
LD = clang++
PROTOC = protoc

CFLAGS = -fcommon -pedantic -O3 -c -std=c++17 -m64 -g -DWIN32 -D_CONSOLE -D_MBCS -D_DEBUG -DMYDEF
LDFLAGS = -O3 -m64 -L. -lm -g

PPDEF = -D
CCINC = -I
CCOUT = -o
LDOUT = -o

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "description": "Swan Simulator JSON test results file schema",
  "properties": {
    "version": {
      "type": "string",
      "description": "Schema version"
    },
  "test_cases": { "type": "array", "items": { "$ref": "#/$defs/TestCase"}}
  },
  "$defs": {
    "TestCase": {
      "description": "One test case (=|swant| harness) and its test items",
      "type": "object",
      "properties": {
        "harness": { "type": "string" },
        "start": { "type": "string", "format": "date-time", "description": "Test execution start datetime (<YYYY>-<MM>-<DD>T<hh>:<mm>:<ss>.<ms>)"},
        "end": { "type": "string", "format": "date-time", "description": "Test execution end datetime (<YYYY>-<MM>-<DD>T<hh>:<mm>:<ss>.<ms>)"},
        "status": { "$ref" : "#/$defs/TestStatus", "description": "Global test case status"},
        "cycles_count": { "type": "integer", "description": "Number of cycles executed" },
        "test_items": { "type": "array", "items": { "$ref": "#/$defs/TestItem"}, "description": "List of test items"}
      },
      "required": ["harness", "start", "end", "status", "cycles_count"]
    },
    "TestStatus": {
      "enum": [ "passed", "failed", "error" ]
    },
    "TestItem": {
      "description": "One test case item description",
      "type": "object",
      "properties": {
        "kind": { "$ref" : "#/$defs/TestItemKind", "description": "Item kind"},
        "model_path": { "type": "string", "description": "Item model path" },
        "passed_count": { "type": "integer", "description": "Number times the item has been successful"},
        "failures": { "type": "array", "items": { "$ref": "#/$defs/Failure"}, "description": "Failures description for this test items"}
      },
      "required": ["kind", "model_path", "passed_count"]
    },
    "TestItemKind": {
      "enum": [ "assert", "oracle" ]
    },
    "Failure": {
      "description": "Test case item failure description",
      "type": "object",
      "properties": {
        "cycle": { "type": "integer", "description": "Cycle number"},
        "actual": { "type": "string", "description": "Actual value" },
        "expected": { "type": "string", "description": "Expected value" },
        "float32_atol": { "type": "number", "description": "Absolute tolerance applied in float32 comparisons" },
        "float32_rtol": { "type": "number", "description": "Relative tolerance applied in float32 comparisons" },
        "float64_atol": { "type": "number", "description": "Absolute tolerance applied in float64 comparisons" },
        "float64_rtol": { "type": "number", "description": "Relative tolerance applied in float64 comparisons" },
        "parts_error_paths": { "type": "array", "items": { "type": "string"}, "description": "Parts in composite flow with comparison error"}
      },
      "required": ["cycle"]
    }
  }
}