------------------------------------------
Release Notes for Trilinos Package Teuchos
------------------------------------------

Trilinos 12.14
--------------

* MINOR: Thread-safe implementation of Teuchos Memory Management classes
  Teuchos::RCP, Teuchos::Ptr, Teuchos::Array, Teuchos::ArrayView, and
  Teuchos::ArrayRCP: This new thread-safe implementation is disabled by
  default but can be enabled by setting -DTeuchos_ENABLE_THREAD_SAFE=ON (which
  is also set when -DTrilinos_ENABLE_THREAD_SAFE=ON is set).  The new
  implementation (thread-safe or non-thread-safe) should be completely
  backward compatible except for not allowing exceptions to be thrown from
  destructors.  The old non-thread-safe implementation would gracefully allow
  exceptions to be thrown from a destructor and maintain the strong guarantee.
  The new implementation will abort when an exception is thrown from a
  destructor while freeing a managed object.

Trilinos 12.0
-------------

* Fixed Teuchos::Ptr::operator=() to catch dangling references (6 April 2015)

Trilinos 11.8
-------------

* New mode for TimeMonitor::summarize (27 Mar 2014)
    
We added a new mode of calculating global statistics to
TimeMonitor::summarize.  The new mode ignores contributions from
processes that either do not have a particular timer, or have a hard
zero for a timer.  This mode is off by default, meaning that the
default summarize behavior is unchanged.
    
This new mode is useful in cases where not all processes have the same
timers and/or some timers are zero.  This can arise when multiple MPI
communicators are in play.  A single call to summarize using a global
communicator yields reasonable statistics for all timers.  The cost is
an additional MPI_Allreduce.
    
Consider this example:
    
  - proc 0 has timers T1=1.0, T2=0.5
  - proc 1 has timers         T2=1.0, T3=1.0
  - proc 2 has timers         T2=2.0, T3=0.5
    
where MCW is a communicator containing 0,1,2, and MC12 is a
communicator containing 1,2.
    
Calling
TimeMonitor::summarize(MCW, std::cout, false, true, false, Teuchos::Union)
yields
    
  - min(T1)=0.0, avg(T1)=0.33, max(T1)=1.0
  - min(T2)=0.5, avg(T2)=1.17, max(T2)=2.0
  - min(T3)=0.0, avg(T3)=0.5,  max(T3)=1.0
    
Calling
TimeMonitor::summarize(MC12, std::cout, false, true, false, Teuchos::Union) 
yields
    
  - min(T1)=0.0, avg(T1)=0.0,  max(T1)=0.0
  - min(T2)=1.0, avg(T2)=1.5,  max(T2)=2.0
  - min(T3)=0.5, avg(T3)=0.75, max(T3)=1.0
    
While each is technically correct for the communicators given, neither
by itself gives information that one might want, namely, averages over
just the processes that have a timer and mins over the nonzero times.
    
With the new mode, calling 
TimeMonitor::summarize(MCW, std::cout, false, true, false, Teuchos::Union, "", true) 
yields
    
  - min(T1)=1.0, avg(T1)=1.0,  max(T1)=1.0
  - min(T2)=0.5, avg(T2)=1.17, max(T2)=2.0
  - min(T3)=0.5, avg(T3)=0.75, max(T3)=1.0

* Ptr: Added is_null() method to match RCP (23 Mar 2014)

* MpiComm: Improved duplicate(), split(), and createSubcommunicator()
  (27 Feb 2014).

These methods now do MPI_Comm_dup, MPI_Comm_split,
resp. MPI_Comm_create, as one would expect.  They also do one less
MPI_Bcast than before.  This is because messages in the new MPI_Comm
(which MPI_Comm_dup, MPI_Comm_split, and MPI_Comm_create all create)
cannot collide with messages in the old MPI_Comm, so there is no need
for a broadcast to agree on a common tag.

Trilinos 11.3:
--------------

(*) Added optional automatic global reductions of pass/fail to Teuchos Unit
Test Harness: Prior to this feature addition, only the result on the root
process of a parallel unit test would determine pass/fail, even if tests on
other proesses failed.  This makes it easier to write parallel unit tests and
results in more robust test code.  For a discussion, see Trilinos issue #5909.
An example can be found in
teuchos/comm/test/UnitTesting/UnitTestHarness_Parallel_UnitTests.cpp (see the
CMakeLists.txt file for how that test is run).  NOTE: By default, no global
reductions of pass/fail are done as to maintain perfect backward
compatibility.

(*) Added new feature to TimeMonitor: You may now enable or disable a
timer (instance of Time) by name.  Disabled timers ignore start() and
stop() calls; calling these methods on a disabled timer does not
change its elapsed time or call count.  Thus, TimeMonitor's
constructor and destructor have no effect on disabled timers.
However, the disabled timers still exist, and TimeMonitor's
summarize() and report() class methods will print statistics for
disabled timers (using their elapsed times and call counts while
enabled).  Enabling a timer does not reset its elapsed time or call
count.  This feature is useful if you want to time only certain
invocations of a particular function that has an internal timer,
without modifying the function's source code.  For an example, see
packages/teuchos/comm/test/Time/TimeMonitor_UnitTests.cpp, line 175
("TimeMonitor, enableTimer" unit test).

Trilinos 11.0:
--------------

(*) Dropped deprecated code in Trilinos 10.12 (see general release notes on
dropping deprecated code).

(*) Teuchos reference BLAS implementations have been corrected to mimic the
behavior of their machine-specific counterparts.  See bugs 4262 and 5683.
This includes fixing the interface to _GER so that the complex instantiation
of that routine uses _GERU.  Also, _ASUM and _IAMAX were corrected to perform
the correct calculations for complex-valued data types.

(*) Fixed SerialDenseSolver class to correctly handle complex-valued data
types.  See bug 5308.  

(*) CommandLineProcessor now properly throws exceptions.  See bug 4668 and
5387.  By default this tool throws exceptions and must recognize all the
options it encounters on the command line.  This is enforced through the
implementation now.  If exception throwing is disabled, then proper error
codes will be returned to the user.

Trilinos 10.13 (dev): 
----------------------

(*) Filtering timer labels for global statistics and output

The computeGlobalTimerStatistics(), report(), and summarize() class
methods of TimeMonitor now support "filtering" timer labels.  See Bug
5301:

https://software.sandia.gov/bugzilla/show_bug.cgi?id=5301

Both methods take an optional "filter" string.  If nonempty, the
methods only print timers whose labels begin with that string.  

This feature could be used to implement "namespaces" for timers.
Trilinos packages may take advantage of this feature by prefixing the
timer name with the package name.  For example: "Teuchos: Timer 1".
Users may exploit this feature to reduce the volume of output.  The
implementation does not compute global statistics for timers that are
filtered out, so filtering could also reduce computation and
communication.

(*) YAML output option for timing results

The report() class method of TimeMonitor now has a YAML output option.
See Bug 5302:

https://software.sandia.gov/bugzilla/show_bug.cgi?id=5302

YAML (see yaml.org) is a recursive acronym for "YAML Ain't Markup
Language."  It "is a human-friendly data serialization standard for
all programming languages."  I've added YAML output on request of
Daniel Barnette (SNL), so that timing results can serve as input data
for his PylotDB (https://github.com/dwbarne/PYLOTDB) framework for
database creation, management, and analysis.  

YAML is not the default output format of report().  To specify YAML
output, give report() a ParameterList with the "Report format"
parameter set to "YAML".  I have provided two different variants of
YAML output: "compact" and "spacious".  The default is "spacious".
You may set this via the "YAML format" parameter.


Trilinos 10.12:
----------------

(*) The current behavior of the Teuchos::XMLParameterListReader has been modified 
to throw an exception (Teuchos::DuplicateParameterSublist) the event that a sublist
is duplicated in an XML stream. This change is disabled by default in the 
XMLParameterListReader class, and is enabled by calling:
    XMLParameterListReader::setAllowsDuplicateSublists( false ) 
This is configured, and thereby constitutes a non-backwards compatible change, 
in the following encapsulating helper methods: 
    Teuchos::updateParametersFromXmlFile(...)
    Teuchos::updateParametersFromXmlFileAndBroadcast(...)
    Teuchos::getParametersFromXmlFile(...)
    Teuchos::updateParametersFromXmlString(...)
    Teuchos::getParametersFromXmlString(...)
This change was requested by Panzer/Drekar developers, to aid in debugging the input
of large XML programs specifying a physics application.

Trilinos 10.10:
----------------


(*) Deprecated the non-namespaced family of TEST_FOR_EXCEPTION(...) macros in
the file Teuchos_TestForException.hpp: There are now namespaced versions
prefixed with TEUCHOS_.

To upgrade client code to use the new namespaced macros, just run:

   teuchos/refactoring/namespace-TestForExceptionMacros.20111017.sh

on your code as:

     $ cd WHATEVER_YOUR_BASE_DIR_IS
     $ $TRILINOS_HOME/packages/teuchos/refactoring/namespace-TestForExceptionMacros.20111017.sh

If client code needs to maintain backward compatibility with older versions of
Trilinos, just leave the code as is and client code will compile and run just
fine without any changes.  This approach, however, will generate deprecated
warnings (unless you turn them off at configure time).



Trilinos 10.8:
--------------


(*) Added automatic stack tracing info for exception messages, segfaults, and
aborts.  Thanks to the work of Ondrej Certik we now have built-in support for
generating strack traces when using g++ when uncaught exceptions are
encountered or when a segfault or about occurs.  See the Doxygen documentation
for more details for how your project can take advantage of this feature.



Trilinos 10.6:
--------------


Nothing to report.



Trilinos 10.4:
--------------


(*) Known breaks in backward compatibility:

- Changed direct constructors for ArrayRCP to take (lowerOffset, size) instead
of (lowerOffset, upperOffset) to be consistent with the nonmember constructors
like arcp(...) and ArrayView.  This was done to make these constructors
consistent with the non-member constructors.  As long clients were using the
nonmember constructors this will not break backward compatibility.  However,
if clients are using the direct constructors, upperOffset becomes size which
means that the size will actually become one less with the upperOffset
becoming one less.  This will therefore not result in memory access errors but
will result in exceptions being thrown when accessing the real last element.
Given the confusion that having diffrent arguments caused (that I got caught
with too) and the inherent safety inthe change, I think this break with strict
backward compatibiity is well worth the (minor) problems it might cause to
users.

- Removed define of TEUCHOS_PRIVIATE_DELETE_NOT_SUPPORTED for _AIX.  The macro
TEUCHOS_PRIVIATE_DELETE_NOT_SUPPORTED was designed to be used only internally
within Teuchos (and perhaps other parts of Trilinos) but at some point all use
of this macro was removed (apparently in all of Trilinos).  If client code
used this macro for their own purposes, then this change will break client
code when _AIX is defined.  However, it seems unlikely that there will be such
client code around.



Trilinos 10.2:
--------------


(*) Default debug enable of RCP node tracing: Setting Teuchos_ENABLE_DEBUG=ON
now sets Teuchos_ENABLE_DEBUG_RCP_NODE_TRACING=ON by default.  This is a more
strict type of checking that will catch more errors.


(*) Known breaks in backward compatibility:

- The type Teuchos_Ordinal has been changed from int to ptrdiff_t by default.
On 64 bit machines, this will be 'long int' instead of 'int'.  This can be
changed back to int by configuring with -DTeuchos_ORDINAL_TYPE:STRING=int.

- The size_type typedef in Teuchos::Array has been changed from size_t to
Teuchos_Ordinal which is now ptrdiff_t, a signed integer which is *not* int on
a 64 bit platform.  See the argument for this in Bugzilla bug 4253.

- The size_type typedef in Teuchos::ArrayView and Teuchos::ArrayRCP has also
been changed to Teuchos_Ordinal to be consistent with Teuchos::Array.

- The size_type typedef in Teuchos::Range1D has been changed to
Teuchos_Ordinal.

- Removed Teuchos_exit.h with the TEUCHOS_EXIT(...) macros.  These were a bad
idea and where never used in Trilinos.  Hopefully no external Trilinos user
made use of these either.

- Non-member functions related to RCPNode tracing have been collected into a
new static class Teuchos::RCPNodeTracer.  Given that no user code should ever
be calling these functions in production code this should not affect most
users.


Trilinos 10.0:
--------------


(*) Known breaks in backward compatibility:

- The raw pointer T* argument in Teuchos::set_extra_data(...) has been
changed to Teuchos::Ptr<T>&.  This requires that you replace:

    Teuchos::set_extra_data(data, dataName, &rcpObj);

with:

    Teuchos::set_extra_data(data, dataName, Teuchos::outArg(rcpObj));
