JSON

The JSONOutput object exists to output values from the Reporter System in the JavaScript Object Notation (JSON) format. Reporter values are arbitrary types, as such the JSON output supports the output of any type if the correct output helper function exists.

Example

The following input snippet demonstrates the default method for enabling JSON output.

[Outputs]
  json = true
[]

The resulting JSON output is generally in the following form, where the time information are provided at the top level and reporters values are nested within a list for the time steps.

{
  "app_name": "main",
  "current_time": "Wed Feb 21 20:23:53 2024",
  "executable": "/data/harblh/worktrees/moose/command_line_rewrite/test/moose_test-opt",
  "executable_time": "Wed Feb 21 20:22:11 2024",
  "libmesh_version": "31948b018e9bea83c138035e952d48065458ba4a",
  "moose_version": "git commit 514922b3fd on 2024-02-07",
  "petsc_version": "3.20.3",
  "reporters": {
    "iteration_info": {
      "type": "IterationInfo",
      "values": {
        "time": {
          "type": "double"
        },
        "timestep": {
          "type": "unsigned int"
        }
      }
    }
  },
  "slepc_version": "3.20.1",
  "time_steps": [
    {
      "iteration_info": {
        "time": 0.0,
        "timestep": 0
      },
      "time": 0.0,
      "time_step": 0
    },
    {
      "iteration_info": {
        "time": 1.0,
        "timestep": 1
      },
      "time": 1.0,
      "time_step": 1
    },
    {
      "iteration_info": {
        "time": 2.0,
        "timestep": 2
      },
      "time": 2.0,
      "time_step": 2
    },
    {
      "iteration_info": {
        "time": 3.0,
        "timestep": 3
      },
      "time": 3.0,
      "time_step": 3
    }
  ]
}

Distributed Output

If a Reporter value is computed with REPORTER_MODE_DISTRIBUTED (see Reporter System a JSON file for each process will automatically be created with the distributed data and the total number of parts and part number for the file will be included in the output.

`to_json` function

In similar fashion to the DataIO functions used for restart and recovery a to_json method must exist for a type to be supported for output to a JSON file. The function is defined in the nlohmann/json library—the library relied upon by MOOSE for JSON support—for this purpose.

For example, the following code snippets show the declaration and definition of the to_json method for the MooseApp object.

void to_json(nlohmann::json & json, const MooseApp & app);

void
to_json(nlohmann::json & json, const MooseApp & app)
{
  if (!app.getSystemInfo())
    return;

  json["app_name"] = app.name();
  json["current_time"] = app.getSystemInfo()->getTimeStamp();
  json["executable"] = app.getSystemInfo()->getExecutable();
  json["executable_time"] = app.getSystemInfo()->getExecutableTimeStamp(json["executable"]);

  json["moose_version"] = MOOSE_REVISION;
  json["libmesh_version"] = LIBMESH_BUILD_VERSION;
#ifdef LIBMESH_DETECTED_PETSC_VERSION_MAJOR
  json["petsc_version"] = std::to_string(LIBMESH_DETECTED_PETSC_VERSION_MAJOR) + "." +
                          std::to_string(LIBMESH_DETECTED_PETSC_VERSION_MINOR) + "." +
                          std::to_string(LIBMESH_DETECTED_PETSC_VERSION_SUBMINOR);
#endif
#ifdef LIBMESH_DETECTED_SLEPC_VERSION_MAJOR
  json["slepc_version"] = std::to_string(LIBMESH_DETECTED_SLEPC_VERSION_MAJOR) + "." +
                          std::to_string(LIBMESH_DETECTED_SLEPC_VERSION_MINOR) + "." +
                          std::to_string(LIBMESH_DETECTED_SLEPC_VERSION_SUBMINOR);
#endif
}

Input Parameters

one_file_per_timestepFalseCreate a unique output file for each time step of the simulation.
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Create a unique output file for each time step of the simulation.
use_displacedFalseEnable/disable the use of the displaced mesh for outputting
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Enable/disable the use of the displaced mesh for outputting
use_legacy_reporter_outputFalseUse reporter output that does not group by object.
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Use reporter output that does not group by object.

Optional Parameters

additional_execute_onThe list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
C++ Type:ExecFlagEnum
Unit:(no unit assumed)
Options:NONE, INITIAL, LINEAR, NONLINEAR_CONVERGENCE, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, FAILED, CUSTOM
Controllable:No
Description:The list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
execute_onINITIAL TIMESTEP_ENDThe list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
Default:INITIAL TIMESTEP_END
C++ Type:ExecFlagEnum
Unit:(no unit assumed)
Options:NONE, INITIAL, LINEAR, NONLINEAR_CONVERGENCE, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, FAILED, CUSTOM
Controllable:No
Description:The list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
output_linearFalseSpecifies whether output occurs on each PETSc linear residual evaluation
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Specifies whether output occurs on each PETSc linear residual evaluation
output_nonlinearFalseSpecifies whether output occurs on each PETSc nonlinear residual evaluation
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Specifies whether output occurs on each PETSc nonlinear residual evaluation

Execution Scheduling Parameters

append_dateFalseWhen true the date and time are appended to the output filename.
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:When true the date and time are appended to the output filename.
append_date_formatThe format of the date/time to append, if not given UTC format is used (see http://www.cplusplus.com/reference/ctime/strftime).
C++ Type:std::string
Unit:(no unit assumed)
Controllable:No
Description:The format of the date/time to append, if not given UTC format is used (see http://www.cplusplus.com/reference/ctime/strftime).
file_baseThe desired solution output name without an extension. If not provided, MOOSE sets it with Outputs/file_base when available. Otherwise, MOOSE uses input file name and this object name for a master input or uses master file_base, the subapp name and this object name for a subapp input to set it.
C++ Type:std::string
Unit:(no unit assumed)
Controllable:No
Description:The desired solution output name without an extension. If not provided, MOOSE sets it with Outputs/file_base when available. Otherwise, MOOSE uses input file name and this object name for a master input or uses master file_base, the subapp name and this object name for a subapp input to set it.
output_if_base_containsIf this is supplied then output will only be done in the case that the output base contains one of these strings. This is helpful in outputting only a subset of outputs when using MultiApps.
C++ Type:std::vector<std::string>
Unit:(no unit assumed)
Controllable:No
Description:If this is supplied then output will only be done in the case that the output base contains one of these strings. This is helpful in outputting only a subset of outputs when using MultiApps.
padding4The number of digits for the extension suffix (e.g., out.e-s002)
Default:4
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:The number of digits for the extension suffix (e.g., out.e-s002)

File Name Customization Parameters

control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Unit:(no unit assumed)
Controllable:No
Description:Adds user-defined labels for accessing object parameters via control logic.
enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:Yes
Description:Set the enabled status of the MooseObject.

Advanced Parameters

end_stepTime step at which this output object stop operating
C++ Type:int
Unit:(no unit assumed)
Controllable:No
Description:Time step at which this output object stop operating
end_timeTime at which this output object stop operating
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Time at which this output object stop operating
min_simulation_time_interval0The minimum simulation time between output steps
Default:0
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:The minimum simulation time between output steps
simulation_time_interval1.79769e+308The target simulation time interval (in seconds) at which to output
Default:1.79769e+308
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:The target simulation time interval (in seconds) at which to output
start_stepTime step at which this output object begins to operate
C++ Type:int
Unit:(no unit assumed)
Controllable:No
Description:Time step at which this output object begins to operate
start_timeTime at which this output object begins to operate
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Time at which this output object begins to operate
sync_onlyFalseOnly export results at sync times
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Only export results at sync times
sync_timesTimes at which the output and solution is forced to occur
C++ Type:std::vector<double>
Unit:(no unit assumed)
Controllable:No
Description:Times at which the output and solution is forced to occur
sync_times_objectTimes object providing the times at which the output and solution is forced to occur
C++ Type:TimesName
Unit:(no unit assumed)
Controllable:No
Description:Times object providing the times at which the output and solution is forced to occur
time_step_interval1The interval (number of time steps) at which output occurs. Unless explicitly set, the default value of this parameter is set to infinity if the wall_time_interval is explicitly set.
Default:1
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:The interval (number of time steps) at which output occurs. Unless explicitly set, the default value of this parameter is set to infinity if the wall_time_interval is explicitly set.
time_tolerance1e-14Time tolerance utilized checking start and end times
Default:1e-14
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Time tolerance utilized checking start and end times
wall_time_interval1.79769e+308The target wall time interval (in seconds) at which to output
Default:1.79769e+308
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:The target wall time interval (in seconds) at which to output

Timing And Frequency Of Output Parameters

execute_reporters_onControl of when Reporter values are output
C++ Type:ExecFlagEnum
Unit:(no unit assumed)
Options:NONE, INITIAL, LINEAR, NONLINEAR_CONVERGENCE, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, FAILED, CUSTOM
Controllable:No
Description:Control of when Reporter values are output
execute_system_information_onINITIALControl when the output of the simulation information occurs
Default:INITIAL
C++ Type:ExecFlagEnum
Unit:(no unit assumed)
Options:NONE, INITIAL, LINEAR, NONLINEAR_CONVERGENCE, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, FAILED, CUSTOM
Controllable:No
Description:Control when the output of the simulation information occurs
hideA list of the variables and postprocessors that should NOT be output to the Exodus file (may include Variables, ScalarVariables, and Postprocessor names).
C++ Type:std::vector<VariableName>
Unit:(no unit assumed)
Controllable:No
Description:A list of the variables and postprocessors that should NOT be output to the Exodus file (may include Variables, ScalarVariables, and Postprocessor names).
showA list of the variables and postprocessors that should be output to the Exodus file (may include Variables, ScalarVariables, and Postprocessor names).
C++ Type:std::vector<VariableName>
Unit:(no unit assumed)
Controllable:No
Description:A list of the variables and postprocessors that should be output to the Exodus file (may include Variables, ScalarVariables, and Postprocessor names).

Selection/Restriction Of Output Parameters

linear_residual_dt_divisor1000Number of divisions applied to time step when outputting linear residuals
Default:1000
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Number of divisions applied to time step when outputting linear residuals
linear_residual_end_timeSpecifies an end time to begin output on each linear residual evaluation
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Specifies an end time to begin output on each linear residual evaluation
linear_residual_start_timeSpecifies a start time to begin output on each linear residual evaluation
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Specifies a start time to begin output on each linear residual evaluation
nonlinear_residual_dt_divisor1000Number of divisions applied to time step when outputting non-linear residuals
Default:1000
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Number of divisions applied to time step when outputting non-linear residuals
nonlinear_residual_end_timeSpecifies an end time to begin output on each nonlinear residual evaluation
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Specifies an end time to begin output on each nonlinear residual evaluation
nonlinear_residual_start_timeSpecifies a start time to begin output on each nonlinear residual evaluation
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Specifies a start time to begin output on each nonlinear residual evaluation

Petsc Linear/Nonlinear Output Parameters

postprocessors_as_reportersFalseOutput Postprocessors values as Reporter values.
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Output Postprocessors values as Reporter values.
vectorpostprocessors_as_reportersFalseOutput VectorsPostprocessors vectors as Reporter values.
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Output VectorsPostprocessors vectors as Reporter values.

Conversions Before Output Parameters

(moose/test/tests/outputs/json/basic/json.i)

[Mesh]
  type = GeneratedMesh
  dim = 1
[]

[Problem]
  solve = false
[]

[Executioner]
  type = Transient
  num_steps = 3
[]

[Reporters]
  [test]
    type = TestDeclareReporter
  []
[]

[Outputs]
  json = true
[]

(moose/test/tests/reporters/iteration_info/gold/limit_out.json)

{
  "app_name": "main",
  "current_time": "Wed Feb 21 20:23:53 2024",
  "executable": "/data/harblh/worktrees/moose/command_line_rewrite/test/moose_test-opt",
  "executable_time": "Wed Feb 21 20:22:11 2024",
  "libmesh_version": "31948b018e9bea83c138035e952d48065458ba4a",
  "moose_version": "git commit 514922b3fd on 2024-02-07",
  "petsc_version": "3.20.3",
  "reporters": {
    "iteration_info": {
      "type": "IterationInfo",
      "values": {
        "time": {
          "type": "double"
        },
        "timestep": {
          "type": "unsigned int"
        }
      }
    }
  },
  "slepc_version": "3.20.1",
  "time_steps": [
    {
      "iteration_info": {
        "time": 0.0,
        "timestep": 0
      },
      "time": 0.0,
      "time_step": 0
    },
    {
      "iteration_info": {
        "time": 1.0,
        "timestep": 1
      },
      "time": 1.0,
      "time_step": 1
    },
    {
      "iteration_info": {
        "time": 2.0,
        "timestep": 2
      },
      "time": 2.0,
      "time_step": 2
    },
    {
      "iteration_info": {
        "time": 3.0,
        "timestep": 3
      },
      "time": 3.0,
      "time_step": 3
    }
  ]
}

(moose/framework/include/outputs/JsonIO.h)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#pragma once

#include "MooseError.h"

#include "nlohmann/json.h"

#include "libmesh/libmesh_common.h"

#include <memory>

class MooseApp;

namespace libMesh
{
class Point;
template <typename T>
class DenseVector;
template <typename T>
class DenseMatrix;
template <typename T>
class NumericVector;
}

// Overloads for to_json, which _must_ be overloaded in the namespace
// in which the object is found in order to enable argument-dependent lookup.
// See https://en.cppreference.com/w/cpp/language/adl for more information
void to_json(nlohmann::json & json, const MooseApp & app); // MooseDocs:to_json

namespace libMesh
{
void to_json(nlohmann::json & json, const Point & p);
void to_json(nlohmann::json & json, const DenseVector<Real> & vector);
void to_json(nlohmann::json & json, const DenseMatrix<Real> & matrix);
void to_json(nlohmann::json & json, const std::unique_ptr<NumericVector<Number>> & vector);
}

namespace nlohmann
{
template <typename T>
struct adl_serializer<std::unique_ptr<T>>
{
  /// Serializer that will output a unique ptr if it exists. We wrap this
  /// with is_constructible_v so that we don't specialize types that
  /// don't already have a specialization. This is required for some earlier
  /// compilers, even though we're not using it at the moment
  static void to_json(json & j, const std::unique_ptr<T> & v)
  {
    if constexpr (std::is_constructible_v<nlohmann::json, T>)
    {
      if (v)
        j = *v;
      else
        j = nullptr;
    }
    else
      mooseAssert(false, "Should not get to this");
  }
};
}

(moose/framework/src/outputs/JsonIO.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "JsonIO.h"
#include "MooseApp.h"
#include "MooseRevision.h"
#include "SystemInfo.h"

#include "libmesh/libmesh_config.h"
#include "libmesh/int_range.h"
#include "libmesh/dense_vector.h"
#include "libmesh/dense_matrix.h"

// MooseDocs:to_json_start
void
to_json(nlohmann::json & json, const MooseApp & app)
{
  if (!app.getSystemInfo())
    return;

  json["app_name"] = app.name();
  json["current_time"] = app.getSystemInfo()->getTimeStamp();
  json["executable"] = app.getSystemInfo()->getExecutable();
  json["executable_time"] = app.getSystemInfo()->getExecutableTimeStamp(json["executable"]);

  json["moose_version"] = MOOSE_REVISION;
  json["libmesh_version"] = LIBMESH_BUILD_VERSION;
#ifdef LIBMESH_DETECTED_PETSC_VERSION_MAJOR
  json["petsc_version"] = std::to_string(LIBMESH_DETECTED_PETSC_VERSION_MAJOR) + "." +
                          std::to_string(LIBMESH_DETECTED_PETSC_VERSION_MINOR) + "." +
                          std::to_string(LIBMESH_DETECTED_PETSC_VERSION_SUBMINOR);
#endif
#ifdef LIBMESH_DETECTED_SLEPC_VERSION_MAJOR
  json["slepc_version"] = std::to_string(LIBMESH_DETECTED_SLEPC_VERSION_MAJOR) + "." +
                          std::to_string(LIBMESH_DETECTED_SLEPC_VERSION_MINOR) + "." +
                          std::to_string(LIBMESH_DETECTED_SLEPC_VERSION_SUBMINOR);
#endif
}
// MooseDocs:to_json_end

namespace libMesh
{
void
to_json(nlohmann::json & json, const libMesh::Point & p)
{
  json["x"] = p(0);
  json["y"] = p(1);
  json["z"] = p(2);
}

void
to_json(nlohmann::json & json, const DenseVector<Real> & vector)
{
  nlohmann::to_json(json, vector.get_values());
}

void
to_json(nlohmann::json & json, const DenseMatrix<Real> & matrix)
{
  std::vector<std::vector<Real>> values(matrix.m(), std::vector<Real>(matrix.n()));
  for (const auto i : make_range(matrix.m()))
    for (const auto j : make_range(matrix.n()))
      values[i][j] = matrix(i, j);
  nlohmann::to_json(json, values);
}

void
to_json(nlohmann::json & json, const std::unique_ptr<NumericVector<Number>> & vector)
{
  mooseAssert(vector, "vector must be non-null");
  std::vector<Number> local_values;
  local_values.reserve(vector->local_size());
  for (const auto i : make_range(vector->first_local_index(), vector->last_local_index()))
    local_values.push_back((*vector)(i));
  nlohmann::to_json(json, local_values);
}
}

Example
Distributed Output
function to_json
Input Parameters