Add stack trace option to CanteraError

Changes proposed in this pull request

Add a static method CanteraError::setStackTraceDepth that can be used to add the top N C++ stack frames to the message of a CanteraError. This can provide additional context on where certain errors are being thrown from.

If applicable, provide an example illustrating new features this pull request is introducing

From Python, instantiate a Solution object where the YAML file specifies a negative temperature for the initial state:

import cantera as ct
ct.CanteraError.set_stack_trace_depth(10)
ct.Solution('broken.yaml')

Now, the Python traceback is followed by the CanteraError message and the top of the C++ stack:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "build/python/cantera/solutionbase.pyx", line 37, in cantera.solutionbase._SolutionBase.__cinit__
    self._cinit(infile=infile, name=name, adjacent=adjacent, origin=origin,
  File "build/python/cantera/solutionbase.pyx", line 75, in cantera.solutionbase._SolutionBase._cinit
    self._init_yaml(infile, name, adjacent, yaml, transport)
  File "build/python/cantera/solutionbase.pyx", line 160, in cantera.solutionbase._SolutionBase._init_yaml
    soln = newSolution(
cantera._utils.CanteraError: 
*******************************************************************************
CanteraError thrown by Phase::setTemperature:
temperature must be positive. T = -300
-------------------------------------------------------------------------------
 0# Cantera::CanteraError::CanteraError(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 1# Cantera::CanteraError::CanteraError<double>(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, double const&) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 2# Cantera::Phase::setTemperature(double) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 3# Cantera::ThermoPhase::setState_TP(double, double) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 4# Cantera::ThermoPhase::setState(Cantera::AnyMap const&) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 5# Cantera::setupPhase(Cantera::ThermoPhase&, Cantera::AnyMap const&, Cantera::AnyMap const&) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 6# Cantera::newThermo(Cantera::AnyMap const&, Cantera::AnyMap const&) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 7# Cantera::newSolution(Cantera::AnyMap const&, Cantera::AnyMap const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::vector<std::__1::shared_ptr<Cantera::Solution>, std::__1::allocator<std::__1::shared_ptr<Cantera::Solution>>> const&, std::__1::map<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>, std::__1::shared_ptr<Cantera::Solution>, std::__1::less<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>>>, std::__1::allocator<std::__1::pair<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const, std::__1::shared_ptr<Cantera::Solution>>>> const&) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 8# Cantera::newSolution(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::vector<std::__1::shared_ptr<Cantera::Solution>, std::__1::allocator<std::__1::shared_ptr<Cantera::Solution>>> const&) in /Users/speth/src/cantera/build/lib/libcantera_shared.3.1.0.dylib
 9# __pyx_pw_7cantera_12solutionbase_13_SolutionBase_9_init_yaml(_object*, _object* const*, long, _object*) in /Users/speth/src/cantera/build/python/cantera/_cantera.cpython-311-darwin.so
*******************************************************************************

Checklist

[x] The pull request includes a clear description of this code change
[x] Commit messages have short titles and reference relevant issues
[x] Build passes (scons build & scons test) and unit tests address code coverage
[x] Style & formatting of contributed code follows contributing guidelines
[x] The pull request is ready for review

Cantera / cantera

Add stack trace option to CanteraError #1730

Codecov Report