Trilinos issueshttps://gitlab.osti.gov/jmwille/Trilinos/-/issues2019-06-08T15:27:26Zhttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/5058Trilinos Framework: Change GCC 4.8.4 PR build to use static libraries2019-06-08T15:27:26ZJames WillenbringTrilinos Framework: Change GCC 4.8.4 PR build to use static libraries*Created by: jwillenbring*
## Enhancement
@trilinos/framework
Our PR testing does not currently include any static library builds. There are important use cases for static libraries, so we want to change one build to use static lib...*Created by: jwillenbring*
## Enhancement
@trilinos/framework
Our PR testing does not currently include any static library builds. There are important use cases for static libraries, so we want to change one build to use static libraries. The GCC 4.8.4 MPI build has been chosen for this enhancement to the PR test suite.https://gitlab.osti.gov/jmwille/Trilinos/-/issues/5070Framework: Autotester runs not reporting2019-06-08T15:27:26ZJames WillenbringFramework: Autotester runs not reporting*Created by: csiefer2*
#5067 #5066
@trilinos/framework @jwillenbring @william76 *Created by: csiefer2*
#5067 #5066
@trilinos/framework @jwillenbring @william76 https://gitlab.osti.gov/jmwille/Trilinos/-/issues/5027Framework: Installation Testing2019-05-06T16:59:22ZJames WillenbringFramework: Installation Testing*Created by: william76*
## Enhancement
@trilinos/framework
@bartlettroscoe
@jwillenbring
As part of the roadmap towards implementing a backwards compatibility test to the Trilinos testing suite we need to first get Installation...*Created by: william76*
## Enhancement
@trilinos/framework
@bartlettroscoe
@jwillenbring
As part of the roadmap towards implementing a backwards compatibility test to the Trilinos testing suite we need to first get Installation Testing up and running.
This will require some updates to [TriBiTS][1] to support some of the installation testing capabilities that we will need. @bartlettroscoe can fill in more details on what we're needing to do there.
[1]: https://tribits.org/Improve productivity, stability, and quality of Trilinoshttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/3178Pull request testing should set -Werror2019-05-02T22:07:04ZJames WillenbringPull request testing should set -Werror*Created by: mhoemmen*
@vbrunini asks whether pull request testing could set `-Werror`, so as to avoid issues like #3177.
@trilinos/framework @khpierson
## Expectations
Trilinos -- at least the library, not necessarily tests a...*Created by: mhoemmen*
@vbrunini asks whether pull request testing could set `-Werror`, so as to avoid issues like #3177.
@trilinos/framework @khpierson
## Expectations
Trilinos -- at least the library, not necessarily tests and examples -- should build warning-free.
## Current Behavior
See #3177. There is an issue that it's impossible to fix warnings in some packages.
## Motivation and Context
Sierra builds with warnings as errors, so they want Trilinos to build warning-free.
## Possible Solution
Exclude legacy packages like ML. Fix warnings. Add `-Werror` to at least one PR build.
## Related Issues
* Related to #3177 Improve productivity, stability, and quality of Trilinoshttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/3958Trilinos needs automated coverage testsing2019-05-02T17:46:20ZJames WillenbringTrilinos needs automated coverage testsing*Created by: bartlettroscoe*
@trilinos/framework
Trilinos currently has no coverage testing. The last coverage build posted to CDash was for MueLu back on 8/20/2018 as shown in [this query](https://testing.sandia.gov/cdash-dev-view...*Created by: bartlettroscoe*
@trilinos/framework
Trilinos currently has no coverage testing. The last coverage build posted to CDash was for MueLu back on 8/20/2018 as shown in [this query](https://testing.sandia.gov/cdash-dev-view/index.php?project=Trilinos&date=2018-11-28&filtercount=2&showfilters=1&filtercombine=and&field1=hascoverage&compare1=1&value1=&field2=buildstarttime&compare2=84&value2=now).
We need regular automated coverage builds posting to CDash.
Improve productivity, stability, and quality of Trilinoshttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/3276Trilinos auto PR tester stability issues2019-05-02T13:20:11ZJames WillenbringTrilinos auto PR tester stability issues*Created by: bartlettroscoe*
@trilinos/framework
## Description
Over the last few weeks and months, the Trilinos auto PR tester has seen several cases where one or more PR builds for a given PR testing iteration failed to produce ...*Created by: bartlettroscoe*
@trilinos/framework
## Description
Over the last few weeks and months, the Trilinos auto PR tester has seen several cases where one or more PR builds for a given PR testing iteration failed to produce results on CDash or showed build or test failures that were not related to the changes on that particular PR.
This Story is to log these fails and keep track of them in order to provide some statistics about these cases in order to inform how to address them. This should replace making comments in individual PRs that exhibit these types of problems like #3260 and #3213.
## PR Builds Showing Random Failures
Below are a few examples of the stability problems (but are not all of the problems).
| PR ID | Num PR Builds to reach passing | First test trigger | Start first test| Passing test | Merge PR |
| --: | --: | --: | --: | --: | --: |
| #3258 | 2 | [8/8/2018 2:35 PM ET](https://github.com/trilinos/Trilinos/pull/3258#issue-207098955) | [8/8/2018 2:44 PM](https://github.com/trilinos/Trilinos/pull/3258#issuecomment-411510956) | [8/8/2018 9:15 PM ET]() | Not merged |
| #3260 | 4 | [8/8/2018 5:22 PM ET](https://github.com/trilinos/Trilinos/pull/3260#issue-207141537) | [8/8/2018 6:31 PM ET](https://github.com/trilinos/Trilinos/pull/3260#issuecomment-411574370) | [8/10/2018 4:13 AM ET](https://github.com/trilinos/Trilinos/pull/3260#issuecomment-412010497) | [8/10/2018 8:25 AM](https://github.com/trilinos/Trilinos/pull/3260#event-1782381644) |
| #3213 | 3 | [7/31/2018 4:30 PM ET](https://github.com/trilinos/Trilinos/pull/3213#issue-205233060) | [7/31/2018 4:57 PM ET](https://github.com/trilinos/Trilinos/pull/3213#issuecomment-409365522) | [8/1/2018 9:48 AM ET](https://github.com/trilinos/Trilinos/pull/3213#issuecomment-409580677) | [8/1/2018 9:53 AM ET](https://github.com/trilinos/Trilinos/pull/3213#event-1765281809) |
| #3098 | 4 | [7/12/2018 12:52 PM ET](https://github.com/trilinos/Trilinos/pull/3098#issue-201063953) | [7/12/2018 1:07 PM ET](https://github.com/trilinos/Trilinos/pull/3098#issuecomment-404582631) | [7/13/2018 11:12 PM ET](https://github.com/trilinos/Trilinos/pull/3098#issuecomment-404994581) | [7/14/2018 10:59 PM ET](https://github.com/trilinos/Trilinos/pull/3098#event-1733896640) |
| #3369 | 6 | [8/29/2018 9:08 AM ET](https://github.com/trilinos/Trilinos/pull/3369#issue-211746901) | [8/29/2018 9:16 AM ET](https://github.com/trilinos/Trilinos/pull/3369#issuecomment-416948915) | [8/31/2018 6:09 AM ET](https://github.com/trilinos/Trilinos/pull/3369#issuecomment-417618824) | [8/31/2018 8:33 AM ET](https://github.com/trilinos/Trilinos/pull/3369#event-1820478271) |
Improve productivity, stability, and quality of Trilinoshttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/5031Framework: PR Reproduction Instructions Failing2019-04-29T17:24:35ZJames WillenbringFramework: PR Reproduction Instructions Failing*Created by: csiefer2*
Finished configuring Trilinos!
-- Configuring incomplete, errors occurred!
With no errors showing up in the cmake output (joy!).
GCC 4.9.3, as it turns out.*Created by: csiefer2*
Finished configuring Trilinos!
-- Configuring incomplete, errors occurred!
With no errors showing up in the cmake output (joy!).
GCC 4.9.3, as it turns out.https://gitlab.osti.gov/jmwille/Trilinos/-/issues/3469Configuration of CUDA-enabled build fails2019-04-18T18:03:54ZJames WillenbringConfiguration of CUDA-enabled build fails*Created by: pelesh*
Configuration of a CUDA-enabled Tpetra/Kokkos build fails at the point where CMake checks for C++ compiler. The error message is:
```
Linking CXX executable cmTC_babeb
/usr/tce/packages/cmake/cmake-3.5.2/bi...*Created by: pelesh*
Configuration of a CUDA-enabled Tpetra/Kokkos build fails at the point where CMake checks for C++ compiler. The error message is:
```
Linking CXX executable cmTC_babeb
/usr/tce/packages/cmake/cmake-3.5.2/bin/cmake -E cmake_link_script
CMakeFiles/cmTC_babeb.dir/link.txt --verbose=1
/usr/tce/packages/openmpi/openmpi-2.0.0-gcc-6.1.0/bin/mpicxx
CMakeFiles/cmTC_babeb.dir/testCXXCompiler.cxx.o -o cmTC_babeb -rdynamic
nvcc fatal : Unknown option 'rdynamic,-fexceptions,-pthread'
gmake[1]: *** [cmTC_babeb] Error 1
```
It seems as if Kokkos' `nvc_wrapper` does not insert `-Xlinker` flags correctly.
I am building from current master branch on a system with following configuration:
```
$ module list
Currently Loaded Modules:
1) StdEnv 2) gcc/6.1.0 3) cuda/9.1.85 4) openmpi/2.0.0 5) cmake/3.5.2
```
The same issue occurs with different openmpi, CUDA, CMake and gcc versions.
I am following Tpetra build instructions from `$Trilinos/packages/tpetra/doc/FAQ.txt`, and I set environment variables like this:
```
export OMPI_CXX=${Trilinos}/packages/kokkos/bin/nvcc_wrapper
export CUDA_LAUNCH_BLOCKING=1
export CUDA_MANAGED_FORCE_DEVICE_ALLOC=1
```
I use following configuration script to set cmake options:
```
#!/bin/bash
cmake \
-D CMAKE_C_COMPILER="mpicc" \
-D CMAKE_CXX_COMPILER="mpicxx" \
-D CMAKE_Fortran_COMPILER="mpif90" \
\
-D Trilinos_CXX11_FLAGS="-std=c++11 --expt-extended-lambda" \
\
-D Trilinos_ENABLE_OpenMP=OFF \
-D TPL_ENABLE_Pthread=OFF \
\
-D Trilinos_ENABLE_Teuchos=ON \
-D Trilinos_ENABLE_Tpetra=ON \
-D Tpetra_INST_SERIAL=ON \
-D Tpetra_INST_OPENMP=OFF \
\
-D Trilinos_ENABLE_Kokkos=ON \
-D Trilinos_ENABLE_KokkosCore=ON \
-D Kokkos_ENABLE_Serial=ON \
-D Kokkos_ENABLE_OpenMP=OFF \
-D Kokkos_ENABLE_Pthread=OFF \
-D Kokkos_ENABLE_Cuda=ON \
-D Kokkos_ENABLE_Cuda_UVM=ON \
-D Kokkos_ENABLE_Cuda_Lambda=ON \
-D Kokkos_ENABLE_Cuda_Relocatable_Device_Code=OFF \
-D TPL_ENABLE_CUDA=ON \
\
-D TPL_ENABLE_MPI=ON \
-D MPI_USE_COMPILER_WRAPPERS=ON \
\
-D Tpetra_INST_CUDA:BOOL=ON \
../Trilinos
```
Any advice how to get past this point would be most appreciated.
https://gitlab.osti.gov/jmwille/Trilinos/-/issues/2150Trilinos Doxygen Guidelines?2019-04-03T07:42:17ZJames WillenbringTrilinos Doxygen Guidelines?*Created by: jmgate*
@trilinos/framework
## Expectations
<!---
Tell us what you think should happen, how you think things should work, what
you would like to see in the documentation, etc.
-->
It'd be great if Trilinos had some...*Created by: jmgate*
@trilinos/framework
## Expectations
<!---
Tell us what you think should happen, how you think things should work, what
you would like to see in the documentation, etc.
-->
It'd be great if Trilinos had some general Doxygen guidelines for developers to follow when documenting the code they write. Has this ever been considered before?
## Current Behavior
<!---
Tell us how the current behavior fails to meet your expectations in some way.
-->
We already have [this Doxygen wiki page](https://github.com/trilinos/Trilinos/wiki/Tools-%7C-Doxygen), but it focusses on how to use Doxygen to automatically generate the documentation for your package. What it doesn't say anything about, though, is what is recommended in terms of documentation in header files of classes, namespaces, functions, data, etc.
I realize Trilinos has historically left matters like this up to the individual packages to decide. Fair enough, but it seems the Trilinos community might be better served if there were some general guidelines from on high that package maintainers could then modify as they see fit.
## Motivation and Context
<!---
How has this expectation failure affected you? What are you trying to
accomplish? Why do we need to address this? What does it have to do with
anything? Providing context helps us come up with a solution that is most
useful in the real world.
-->
I come across *way* too much undocumented code on a regular basis. I imagine that's largely due to work being done quick and dirty in a fast-paced research environment—*c'est la vie*. I'd guess the problem is also compounded by the number of short-term developers (interns/postdocs/etc.) we have working on Trilinos. Left unaddressed, the problem will just continue to get worse.
I'm not saying we should drop everything, go back, and document everything that's been left undocumented over the years—actually I just might say that if you pressed me on it. I am saying it'd be awful nice to have some guidelines in place such that new code that gets added is heading us in the right direction.
## Definition of Done
<!---
Tell us what needs to happen. If necessary, give us a task lisk along the
lines of:
-->
- [ ] Figure out if Trilinos should have such guidelines.
- [ ] If so, figure out where they should live.
- [ ] Figure out what should be in them.
- [ ] Get them out there.
- [ ] Point Trilinos developers to them.
## Possible Solution
<!---
Not obligatory, but suggest a fix for the bug or documentation, or suggest
ideas on how to implement the addition or change.
-->
Here are some Doxygen guidelines I whipped up recently for one of the applications I'm on, modified slightly to apply to Trilinos.
<details>
<summary>
<b>Sample Doxygen Guidelines</b> (click to expand)
</summary>
<br>
Trilinos uses [Doxygen](http://www.stack.nl/~dimitri/doxygen/index.html) to generate documentation from annotated source code.
# Documenting a Class or Struct
> **Note:** The documentation of a `struct` is the same as that required for a `class` as they are essentially the same thing, differing only in the default visibility of their members.
## The Class Itself
Classes should be preceded by a comment block along these lines:
```c++
/**
* \brief A brief description of the class goes here. The brief description
* is terminated by a blank line.
*
* The detailed description of the class follows the blank line. This should
* give an unfamiliar developer enough information to understand the purpose
* of the class and how to interact with instantiations of it via the methods
* that will be defined below.
*
* If a detailed description continues over multiple paragraphs, separate
* paragraphs with a blank line.
*/
template<stuff>
class ClassName
:
public BaseClass<stuff>
{
// Insert class definition here.
} // end of class ClassName
```
## Functions
Within the class definition, functions should be preceded by a comment block along these lines:
```c++
/**
* \brief A brief description of the function goes here. The brief
* description is terminated by a blank line.
*
* The detailed description of the function follows the blank line. This
* should give an unfamiliar developer an understanding of what the function
* is doing and why you would use it.
*
* \note If anything is noteworthy, feel free to include that here. Perhaps
* you might mention how this compares to another function in the class,
* if it is to be preferred over another method, if it has been
* deprecated and should no longer be used, etc. Similar commands you
* can use in this manner are `\remark` and `\warning`.
*
* \param[in,out] arg1 This is a description of `arg1`. This variable is used
* as both input and output; that is, its value changes
* and persists after the function call.
* \param[out] arg2 This is a description of `arg2`. This variable is used
* as output; its value when the function begins is
* irrelevant.
* \param[in] arg3 This is a description of `arg3`. Be sure to mention
* that it's inclusion is optional, and if omitted, what
* the default value is.
*
* \pre This is some precondition that must be satisfied before the function
* executes.
*
* \post This is some postcondition that will be satisfied after the function
* executes.
*
* \throws ExceptionType This is a description of why `ExceptionType` would be
* thrown in the midst of the function execution.
*
* \returns This is a description of what the function returns on completion,
* if anything.
*/
returnType
functionName(
someType arg1,
anotherType arg2,
yetAnotherType arg3 = someDefaultValue);
```
If any of the lines in the comment block above (`\note`, `\warning`, `\param`, `\throws`, `\returns`) are not applicable to the function you're documenting, simply omit them.
## Member Data
Member data should be preceded by a comment block along these lines:
```c++
/**
* \brief A brief description of the data goes here. The brief description
* is terminated by a blank line.
*
* The detailed description of the data follows the blank line. If the brief
* description gives enough information to understand the variable, its use
* and purpose, then a detailed description may not be necessary.
*/
DataType
member_data_;
```
## Enumerations
When documenting an `enum`, use something along the lines of the following:
```c++
/**
* \brief A brief description of the enum goes here. The brief
* description is terminated by a blank line.
*
* The detailed description of the enum follows the blank line. This should
* give an unfamiliar developer an understanding of what the enum represents
* and how it is used.
*/
enum EnumName
{
SOMETHING, /*!< This is a description of the SOMETHING value of the enum.
It can be as detailed as you like. */
SOMETHING_ELSE /*!< This is a description of SOMETHING_ELSE. */
}; // end of enum EnumName
```
## Typedefs and Usings
When documenting a `typedef`, the syntax is essentially the same as that used for member data:
```c++
/**
* \brief A brief description of the typedef goes here. The brief
* description is terminated by a blank line.
*
* The detailed description of the typedef follows the blank line. If the
* brief description gives enough information to understand the typedef, its
* use and purpose, then a detailed description may not be necessary.
*/
typedef OriginalType NewName;
```
However, as of C++11, we should really be phasing out `typedef`s in favor of `using` statements. Unfortunately, Doxygen has not been updated to support those out of the box, so it needs a little help. We can use the `\var` command to tell Doxygen to document a `using` statement as if it were a variable:
```c++
/**
* \var NewName
*
* \brief A brief description of the using statement goes here. The brief
* description is terminated by a blank line.
*
* The detailed description of the using statement follows the blank line.
* If the brief description gives enough information to understand the
* using statement, then a detailed description may not be necessary.
*/
using NewName = OriginalType;
```
## Grouping Entities
You may find it useful to group certain functions, variables, etc., together into named sections, particularly if your class contains a great many members. This can aid in understanding the design and intended use of the class. To group entities together in the documentation, use the following:
```c++
//-----------------------------------------------------------------------------
/* */
/** \name Group 1 Name */
/** @{ */
//-----------------------------------------------------------------------------
// Insert functions, variables, typedefs, etc., here, along with their
// documentation.
//-----------------------------------------------------------------------------
/** @} */
/* end of Group 1 Name */
/* */
//-----------------------------------------------------------------------------
```
Be sure not to forget the `/** @{ */` and `/** @} */`, which open and close the group.
> **Note:** These grouping characters must appear on their own lines. If they're on a line with other non-comment characters, Doxygen won't process them correctly.
Alternatively, if you wish to define a few groups in succession, you could use the following:
```c++
//-----------------------------------------------------------------------------
/* */
/** \name Group 1 Name */
/** @{ */
//-----------------------------------------------------------------------------
// Insert functions, variables, typedefs, etc., here, along with their
// documentation.
//-----------------------------------------------------------------------------
/** @} */
/** \name Group 2 Name */
/** @{ */
//-----------------------------------------------------------------------------
// Insert more stuff here, along with its documentation.
//-----------------------------------------------------------------------------
/** @} */
/* end of Group 2 Name */
/* */
//-----------------------------------------------------------------------------
```
### Documenting the Group Itself
If you like, you can include documentation that pertains to all members of a group. To do so, use something along the lines of:
```c++
//-------------------------------------------------------------------------------
/**
* \name Group Name
* @{
*
* This is a detailed description that pertains to all the members of this
* group.
*
* \param[in] x - This is an input that pertains to every member of the group.
*
* \returns This is something every member of the group returns, at least in
* some general sense.
*/
//-------------------------------------------------------------------------------
// Insert the members of the group, along with any corresponding documentation.
// You can either document just the first member (see below) or document each
// member separately.
//-----------------------------------------------------------------------------
/** @} */
/* end of Group Name */
/* */
//-----------------------------------------------------------------------------
```
This documentation will appear between the group name and its members in the brief description section of the automatically generated HTML page, but it will not appear with the detailed documentation of any of the members.
### Only Documenting the First Member
If `DISTRIBUTE_GROUP_DOC=YES` in your Doxygen configuration, the documentation on the first member of a group will get spread across all members of the group in the generated HTML. This can be useful, for instance, if you have a handful of functions that all do more or less the same thing—you can document them once in the code, but someone using the Doxygen as a reference manual will be able to see that documentation regardless of which function in the group they happen to be looking at.
For instance, if you have
```c++
//-----------------------------------------------------------------------------
/* */
/** \name Random Generators */
/** @{ */
//-----------------------------------------------------------------------------
/**
* \brief Get a random variable.
*
* Generate a random `int`/`double`/`char`/`string`.
*/
int rand();
double rand();
char rand();
std::string rand();
//-----------------------------------------------------------------------------
/** @} */
/* end of Random Generators */
/* */
//-----------------------------------------------------------------------------
```
the generated HTML will be such that it'll look like you copied and pasted the comment before `int rand()` in front of the other three routines.
> **Note:** If you do not wish all members of a group to share the same documentation, *each and every member must be documented separately*.
# Documenting a Namespace
Namespaces appear throughout our code, but if documentation were to show up before each occurrence of a namespace, those various bits of documentation will get bundled together by Doxygen in a manner depending on in what order it processes the files. To avoid the potential confusion there, namespaces should be documented in `Trilinos/packages/packageName/src/Namespaces.hpp` (or if your package contains subpackages, you could have a `Trilinos/packages/packageName/subpackageName/src/Namespaces.hpp` for each subpackage). Each namespace should be preceded by a comment block along these lines:
```c++
/**
* \brief A brief description of the namespace goes here. The brief
* description is terminated by a blank line.
*
* The detailed description of the namespace follows the blank line. This
* should give an unfamiliar developer enough information to understand the
* purpose of the namespace, what it contains, why it was organized in such a
* way, etc.
*
* If the detailed description continues over multiple paragraphs, separate
* paragraphs with a blank line.
*/
namespace something
{
} // end of namespace something
```
Nothing need to be in the namespace in `Namespaces.hpp`, other than any nested namespaces and their associated documentation.
# General Doxygen Guidelines
The [Doxygen manual](http://www.stack.nl/~dimitri/doxygen/manual/index.html) will tell you everything you need to know about using Doxygen to document your code. Here are some highlights:
## Todos
If, for whatever reason, you are unable to complete the documentation of a class, function, variable, etc.—perhaps you need to consult with a coworker to ensure you have an accurate description of what you're documenting—be sure to use the `\todo` command to flag this as documentation that still needs work. For instance,
```c++
/**
* \brief This function does something really cool.
*
* But I'm not entirely sure what it is yet.
*
* \todo Finish documenting this function.
*/
returnType
awesomeFunction();
```
If `GENERATE_TODOLIST=YES` in your Doxygen configuration, `\todo` items populate the "Todo List" page under the "Related Pages" tab of your package's Doxygen site, so it's easy to see what still needs work.
## Undocumented Entities
When you run Doxygen, for instance,
```bash
cd path/to/Trilinos/packages/packageName/docs
./builddocs.sh |& tee doxygen.log
```
it will warn you about any undocumented entities. You can search through the output for warnings associated with files you've touched to ensure you haven't missed documenting anything. For instance,
```bash
grep warning doxygen.log | grep FileIModified.hpp
```
## Comment Blocks
Note that in the midst of Doxygen-style comment blocks
```c++
/**
* Text
* goes
* here.
*/
```
any leading `*` marks are stripped out by Doxygen before any other processing is done.
## Automatic Link Generation
Doxygen will [automatically generate hyperlinks](http://www.stack.nl/~dimitri/doxygen/manual/autolink.html) in a handful of scenarios. When mentioning a function, be sure to include `()` at the end to tell Doxygen to generate a link to that function's documentation, as in
```c++
/**
* Check out `functionName()`. It's pretty great.
*/
```
## Markdown Syntax
Doxygen does have support for rendering [Markdown syntax](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html).
When it comes to documenting classes, functions, and data as specified above, be sure to use `` `backticks` `` around class names, function names, and snippets of code that appear inline to have them rendered in a monospaced font.
If creating a bulleted list, use non-asterisk bullet markers, as leading asterisks will be stripped away. That is, prefer this
```c++
/**
* Here's a list:
* - Item 1
* - Item 2
*/
```
to this
```c++
/**
* Here's a list:
* * Item 1
* * Item 2
*/
```
## Including Math
Doxygen allows you to include mathematical formulas and the like by surrounding LaTeX with certain delimiters:
* `\f$` for inline math, as in `\f$ E = m c^2 \f$`;
* `\f[` and `\f]` for unnumbered displayed equations, analogous to `\begin{equation*}` and `\end{equation*}`; and
* `\f{environment}{` and `\f}` for other LaTeX math environments, such as `eqnarray`.
See [this documentation](http://www.stack.nl/~dimitri/doxygen/manual/formulas.html) for examples.
## Including Code
There are a handful of different ways to include code blocks in Doxygen, but the one that seems to work in the widest variety of cases is the following:
```c++
/**
* Here's a bit of code
* \code{.cpp}
int
main(
int argc,
char* argv[])
{
std::cout << "Hello World!" << std::endl;
} // end of main()
\endcode
* that prints "Hello World!".
*/
```
The argument to the `\code{}` command is a file extension that'll tell Doxygen what kind of syntax highlighting it should use. Unfortunately, between the `\code{}` and `\endcode` keywords, there is no stripping of leading asterisks as would normally take place. It will, however, strip out whatever leading indentation exists.
# Trilinos' Policy
At a bare minimum, Trilinos requires that any new entities you add have a `\brief` description, and functions additionally require at least the `\param`s and `\returns` information. It is the responsibility of the developer adding the new code to include the relevant documentation. It is the responsibility of the pull request reviewer to not allow a request to be merged until this minimum documentation is in place.
It is also highly recommended that any time you come across undocumented entities, that you either add the documentation yourself if you are knowledgable enough to do so, or contact the file author and ask them to add the documentation. Our goal is to have a fully documented code base, and the more proactive every developer is about that, the easier it will be to achieve.
</details>https://gitlab.osti.gov/jmwille/Trilinos/-/issues/3585Test Anasazi_Epetra_OrthoManagerGenTester_0_MPI_4 appears to be randomly fail...2019-04-02T18:21:50ZJames WillenbringTest Anasazi_Epetra_OrthoManagerGenTester_0_MPI_4 appears to be randomly failing in many builds including CI, PR, and ATDM builds*Created by: bartlettroscoe*
CC: @trilinos/framework, @trilinos/anasazi, @srajama1 (Trilinos Linear Solver Product Area Lead)
## Next Action Status
PR #4052 merged to 'develop' on 12/18/2018 but still failing after that. Next: Tr...*Created by: bartlettroscoe*
CC: @trilinos/framework, @trilinos/anasazi, @srajama1 (Trilinos Linear Solver Product Area Lead)
## Next Action Status
PR #4052 merged to 'develop' on 12/18/2018 but still failing after that. Next: Try to fix again?
## Description
It would seem that the test `Anasazi_Epetra_OrthoManagerGenTester_0_MPI_4` is very occasionally randomly failing in various builds. As shown in [this query](https://testing.sandia.gov/cdash-dev-view/queryTests.php?project=Trilinos&date=2018-10-09&filtercount=4&showfilters=1&filtercombine=and&field1=testname&compare1=61&value1=Anasazi_Epetra_OrthoManagerGenTester_0_MPI_4&field2=status&compare2=61&value2=failed&field3=details&compare3=64&value3=timeout&field4=buildstarttime&compare4=83&value4=2018-07-01), this test failed 10 times since 7/1/2018 in the builds:
* `Linux-GCC-4.8.4-MPI_RELEASE_DEBUG_SHARED_PT_OPENMP_CI` (post-push CI build): 1 time (today)
* `PR-XXXX-test-Trilinos_pullrequest_gcc_4.9.3-YYYY` (standard PR build): 4 times
* `PR-XXXX-test-Trilinos_pullrequest_gcc_4.8.4-YYYY` (standard PR build): 1 time
* `Trilinos-atdm-chama-intel-debug-openmp` (standard ATDM build): 1 time
* `Trilinos-atdm-rhel6-gnu-opt-openmp` (standard ATDM build): 2 times
* `Trilinos-atdm-waterman-cuda-9.2-debug` (standard ATDM build): 1 time
In each of these 10 failures in the last 3 months, such as the CI failure today shown [here](https://testing.sandia.gov/cdash-dev-view/testDetails.php?test=56264374&build=4031303), it shows failures like:
```
projectAndNormalizeGen() returned rank 5
|| <S,S> - I || after : 2.65912e-11
1|| S_in - X1*C1 - X2*C2 - S_out*B || : 1.70776e-09
vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv tolerance exceeded! test failed!
```
The location of these failures seems to change in this test but all of the failures appear to be "tolerance exceeded! test failed!"
Is there some type of non-deterministic behavior in this test or in the underlying Anasazi code that allows for these types of random failures?
## Steps to Reproduce
Given that this test seems to be failing randomly only very occasionally, this might be hard to reproduce locally. But given that this has failed in the post-push GCC 4.8.4 CI build and the GCC 4.9.3 PR build one might be able to use one of those.
Keep promoted "ATDM" builds of Trilinos cleanhttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/4775Trilinos PR testing missed Ifpack2 compile issue2019-04-01T16:23:52ZJames WillenbringTrilinos PR testing missed Ifpack2 compile issue*Created by: prwolfe*
From issue #4742
> Hmmm, this is short on details, but I just ran into an issue when using a recent master checkout of Trilinos.
>
> Basically lines 2472 and 2478 in the file packages/ifpack2/src/Ifpack2_Blo...*Created by: prwolfe*
From issue #4742
> Hmmm, this is short on details, but I just ran into an issue when using a recent master checkout of Trilinos.
>
> Basically lines 2472 and 2478 in the file packages/ifpack2/src/Ifpack2_BlockTriDiContainer_impl.hpp are using a const instance of a class (Kokkos::TeamPolicy) to call a const function for a non-const instance. Being named a "set" function I tried removing the "const" from the call in Ifpack2_BlockTriDiContainer_impl.hpp and got a clean build.
>
> The $6 question is how did this get through Trilinos testing and how do we fix that. This is a very simple issue which should have been caught early.
>
> _Originally posted by @prwolfe in https://github.com/trilinos/Trilinos/issues/4742#issuecomment-478109186_
>
This issue is to resolve what is missing in the testing and how to resolve that.https://gitlab.osti.gov/jmwille/Trilinos/-/issues/2597Elevate all packages and SE packages used by ATDM APPs to Primary Tested2019-03-29T19:34:21ZJames WillenbringElevate all packages and SE packages used by ATDM APPs to Primary Tested*Created by: bartlettroscoe*
**CC:** @trilinos/framework, @fryeguy52
**Blocked By:** #4219, #4272
## Description:
Currently, it seems that some of the subpackages used by the ATDM EMPIRE APP are labeled Secondary Tested (ST)....*Created by: bartlettroscoe*
**CC:** @trilinos/framework, @fryeguy52
**Blocked By:** #4219, #4272
## Description:
Currently, it seems that some of the subpackages used by the ATDM EMPIRE APP are labeled Secondary Tested (ST). Since ST is enabled by default with Trilinos in the EMPIRE Trilinos configuration, this makes sense that that would have happened. However, by definition, anything being used by ATDM APPs should be treated as Primary Tested (see [here](http://trac.trilinos.org/wiki/TribitsLifecycleModelOverview#test_categories)).
Therefore, this story is to identify which Trilinos subpackages are really being used by ATDM that are currently categorized as ST and elevate them to PT.
https://gitlab.osti.gov/jmwille/Trilinos/-/issues/4621Allow Trilinos users to set Labels2019-03-18T12:45:16ZJames WillenbringAllow Trilinos users to set Labels*Created by: bartlettroscoe*
@trilinos/framework
The instructions for creating new GitHub issues at:
* https://github.com/trilinos/Trilinos/wiki/Managing-Trilinos-Project-Issues
and even the GitHub issue template at:
* http...*Created by: bartlettroscoe*
@trilinos/framework
The instructions for creating new GitHub issues at:
* https://github.com/trilinos/Trilinos/wiki/Managing-Trilinos-Project-Issues
and even the GitHub issue template at:
* https://raw.githubusercontent.com/trilinos/Trilinos/master/.github/ISSUE_TEMPLATE.md
tells users to set Issue Labels but it it is reported in https://github.com/trilinos/Trilinos/issues/4616#issuecomment-472939081 that users can't actually set labels.
Is there any reason we can't allow users to set labels on Trilinos GitHub Issues like they are being told to do?
Improve productivity, stability, and quality of Trilinoshttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/4461Framework: Autotester Occasionally Refuses to Do Inspection2019-03-08T17:10:35ZJames WillenbringFramework: Autotester Occasionally Refuses to Do Inspection*Created by: csiefer2*
Which means you can't merge a tested, approved PR.
This can be 'fixed' by throwing on 'AT: RETEST' and burning another 4 hours of testing time (if the test machines all work), but this is getting annoying.
@...*Created by: csiefer2*
Which means you can't merge a tested, approved PR.
This can be 'fixed' by throwing on 'AT: RETEST' and burning another 4 hours of testing time (if the test machines all work), but this is getting annoying.
@trilinos/framework @william76 @jwillenbring https://gitlab.osti.gov/jmwille/Trilinos/-/issues/4571Long file names in KokkosKernels have broken git clone of Trilinos on Windows2019-03-07T19:52:38ZJames WillenbringLong file names in KokkosKernels have broken git clone of Trilinos on Windows*Created by: bartlettroscoe*
CC: @trilinos/framework, @trilinos/kokkos-kernels
## Description
It appears that the Trilinos git repo has gotten into a state where it can't even be cloned on Windows systems with git.
The CASL PH...*Created by: bartlettroscoe*
CC: @trilinos/framework, @trilinos/kokkos-kernels
## Description
It appears that the Trilinos git repo has gotten into a state where it can't even be cloned on Windows systems with git.
The CASL PHI INF lead @lefebvrera reported the following error when trying to clone the current Trilinos git repo just a short time ago:
```
G:\raq\scale_dev\dev>git clone https://github.com/trilinos/Trilinos.git Trilinos
Cloning into 'Trilinos'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (40/40), done.
remote: Total 957120 (delta 17), reused 14 (delta 7), pack-reused 957073
Receiving objects: 100% (957120/957120), 562.05 MiB | 26.56 MiB/s, done.
Resolving deltas: 100% (771153/771153), done.
error: unable to create file packages/kokkos-kernels/src/impl/generated_specializations_cpp/gauss_seidel_numeric/KokkosSparse_gauss_seidel_numeric_eti_spec_inst_Kokkos_complex_double__size_t_int64_t_LayoutRight_Cuda_CudaHostPinnedSpace_CudaHostPinnedSpace.cpp: Filename too long
error: unable to create file packages/kokkos-kernels/src/impl/generated_specializations_cpp/gauss_seidel_symbolic/KokkosSparse_gauss_seidel_symbolic_eti_spec_inst_Kokkos_complex_double__size_t_int64_t_LayoutLeft_Cuda_CudaHostPinnedSpace_CudaHostPinnedSpace.cpp: Filename too long
error: unable to create file packages/kokkos-kernels/src/impl/generated_specializations_cpp/gauss_seidel_symbolic/KokkosSparse_gauss_seidel_symbolic_eti_spec_inst_Kokkos_complex_double__size_t_int64_t_LayoutRight_Cuda_CudaHostPinnedSpace_CudaHostPinnedSpace.cpp: Filename too long
error: unable to create file packages/kokkos-kernels/src/impl/generated_specializations_cpp/gauss_seidel_symbolic/KokkosSparse_gauss_seidel_symbolic_eti_spec_inst_Kokkos_complex_float__size_t_int64_t_LayoutLeft_Cuda_CudaHostPinnedSpace_CudaHostPinnedSpace.cpp: Filename too long
error: unable to create file packages/kokkos-kernels/src/impl/generated_specializations_cpp/gauss_seidel_symbolic/KokkosSparse_gauss_seidel_symbolic_eti_spec_inst_Kokkos_complex_float__size_t_int64_t_LayoutRight_Cuda_CudaHostPinnedSpace_CudaHostPinnedSpace.cpp: Filename too long
Checking out files: 100% (56578/56578), done.
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry the checkout with 'git checkout -f HEAD'
```
https://gitlab.osti.gov/jmwille/Trilinos/-/issues/2221Pamgen,kokkos-kernels: NVCC build error with -D CMAKE_CXX_USE_RESPONSE_FILE_F...2019-03-05T22:14:10ZJames WillenbringPamgen,kokkos-kernels: NVCC build error with -D CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS=ON*Created by: mhoemmen*
kokkos-kernels requires `-D CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS=ON` for CUDA builds, even with complex arithmetic disabled.
https://github.com/trilinos/Trilinos/issues/2115#issuecomment-357750048
However...*Created by: mhoemmen*
kokkos-kernels requires `-D CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS=ON` for CUDA builds, even with complex arithmetic disabled.
https://github.com/trilinos/Trilinos/issues/2115#issuecomment-357750048
However, Pamgen does not build, given those settings.
@trilinos/kokkos-kernels @trilinos/pamgen @trilinos/framework
CC: @rrdrake @prwolfe
## Expectations
1. Whatever flags kokkos-kernels needs to build on CUDA, they need not to block building other essential packages.
2. kokkos-kernels needs to document its CMake requirements.
3. kokkos-kernels needs to fail at configure time, with an informative message, if the CMake variables that it needs are not set.
## Current Behavior
```
$ make
[ 0%] Linking CXX shared library libpamgen.so
nvcc fatal : No input files specified; use option --help for more information
make[2]: *** [packages/pamgen/src/libpamgen.so.12.13] Error 1
make[1]: *** [packages/pamgen/src/CMakeFiles/pamgen.dir/all] Error 2
make: *** [all] Error 2
```
## Motivation and Context
Many downstream tests, including Belos and Ifpack2, depend on Pamgen. This blocks adequate Trilinos testing on CUDA.
## Steps to Reproduce
```
$ module list
Currently Loaded Modulefiles:
1) sems-env 3) sems-cmake/3.3.2 5) kokkos-cuda/8.0.44
2) kokkos-env 4) sems-gcc/5.3.0 6) kokkos-openmpi/2.0.1/cuda
```
CMake configuration:
```
-D Trilinos_ENABLE_EXPLICIT_INSTANTIATION:BOOL=ON
-D BUILD_SHARED_LIBS:BOOL=ON
-D Trilinos_ENABLE_OpenMP:BOOL=ON
-D Kokkos_ENABLE_OpenMP:BOOL=ON
-D Tpetra_INST_OPENMP:BOOL=ON
-D Trilinos_SHOW_DEPRECATED_WARNINGS:BOOL=ON
-D Trilinos_ENABLE_Fortran:BOOL=OFF
-D TPL_ENABLE_CUDA:BOOL=ON
-D KOKKOS_ARCH="SNB;Kepler35"
-D Kokkos_ENABLE_Cuda:BOOL=ON
-D Kokkos_ENABLE_Cuda_UVM:BOOL=ON
-D Tpetra_INST_CUDA:BOOL=ON
-D Kokkos_ENABLE_Cuda_Lambda:BOOL=ON
-D CMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS:BOOL=ON
-D CMAKE_CXX_FLAGS:STRING="-Wall"
-D Trilinos_CXX11_FLAGS:STRING="-std=c++11 --expt-extended-lambda"
-D TPL_ENABLE_MKL:BOOL=OFF
-D TPL_ENABLE_Matio:BOOL=OFF
-D TPL_ENABLE_SuperLU:BOOL=OFF
-D TPL_ENABLE_Zlib:BOOL=OFF
-D TPL_ENABLE_Netcdf:BOOL=OFF
-D TPL_ENABLE_HDF5:BOOL=OFF
-D TPL_ENABLE_ParMETIS:BOOL=OFF
-D TPL_ENABLE_Boost:BOOL=OFF
-D TPL_ENABLE_BoostLib:BOOL=OFF
-D TPL_ENABLE_yaml-cpp:BOOL=OFF
-D TPL_ENABLE_MPI:BOOL=ON
```
## Your Environment
- develop branch, commit 400765e21e17dfb995e0f4a2759ce9c5f961b685 (likely not related)
## Related Issues
* Blocks #2115 https://gitlab.osti.gov/jmwille/Trilinos/-/issues/4269Propose new Trilinos release model2019-03-03T18:38:58ZJames WillenbringPropose new Trilinos release model*Created by: mhoemmen*
@trilinos/framework @maherou @jwillenbring @bartlettroscoe
PR https://github.com/trilinos/Trilinos/pull/4259 led to a discussion about Trilinos versions, deprecation, and the Trilinos release model. I wanted ...*Created by: mhoemmen*
@trilinos/framework @maherou @jwillenbring @bartlettroscoe
PR https://github.com/trilinos/Trilinos/pull/4259 led to a discussion about Trilinos versions, deprecation, and the Trilinos release model. I wanted to summarize that here, and propose the following:
- Drop the official policy (which we haven't followed for years anyway)
- Embrace the current de facto policy (which I'll summarize below)
- Help users write code that works with multiple Trilinos package "versions"
# Official policy
Here is Trilinos' official policy:
1. Minor release every quarter
2. Major release every year
3. Backwards compatibility breaks only at major releases
4. If you want to break an interface, you must deprecate it the last minor release before a major release
When was the last time we did any of this? At least three years? We made a 12.14 release _tag_, but I wouldn't call that a "release" in any sense. @crtrott and I spent a ridiculous effort in Tpetra not to break backwards compatibility when we converted it to use Kokkos 2.0; the utter lack of interest in the release policy post 12.0 makes me feel like that was a waste of time.
# De facto policy
@ikalash, @rrdrake, @theguruat12, @micahahoward, @rppawlo, or @trilinos/framework may wish to chime in, but I would summarize the de facto "Trilinos versioning" policy for many internal applications as follows:
1. App either forks Trilinos, or picks a Trilinos "master" branch commit.
2. App defines its own acceptance testing for Trilinos.
3. When an app wants to update its Trilinos, it uses acceptance tests to decide when to merge / pull.
Many apps facilitate this by testing the app nightly against current master Trilinos.
4. Apps put pressure on Trilinos as needed to support their goals. Individual Trilinos developers use guidance from their managers to prioritize.
This implies that apps define their own "Trilinos versions." Apps actually get work done with this model. That, along with open access to Trilinos' repo on GitHub, likely explains the lack of enthusiasm for official Trilinos releases. I've gotten about as many complains about deprecation warnings ("hey, we can't build warning-free") as I've gotten about actual interface changes, so it's likely less effort just to break the build than it is to do an official deprecation (how long? who knows, since no official releases!).
# Help users write code that works with multiple Trilinos "versions"
What's missing from this model is a way for an app to work correctly with multiple Trilinos package versions at once. For example:
```c++
void my_app_function () {
#if PACKAGE_FOO_VERSION < SOME_MINIMUM
old_foo_function ();
#else
new_foo_function ();
#endif
}
```
A few packages have added this feature themselves. For example, Kokkos has a CMake option and macro to help manage deprecation. Tpetra just recently added this.
# Proposal
I propose the following:
1. Support the current de facto policy (see above).
2. Packages that have enough users to care, should define their own release cycle and policies.
3. Such packages should define macros to enable or disable deprecated code.
4. Such packages should define macros to test the version number in code. Version number can be whatever the package wants, as long as users can test when it increases.
The only packages that would need to opt in, are packages with external users who care about this policy, and whose interfaces change. Kokkos does all of these but (4), and (4) isn't hard (Kokkos has an outstanding issue to implement it).
# Summary
1. Embrace what we're doing now anyway.
2. Packages who care can add their own version macros.
What do y'all think?Improve productivity, stability, and quality of Trilinoshttps://gitlab.osti.gov/jmwille/Trilinos/-/issues/1782Add metis tpl to Trilinos testing2019-02-26T16:43:40ZJames WillenbringAdd metis tpl to Trilinos testing*Created by: bmpersc*
@trilinos/framework The @trilinos/shylu team needs metis to be a tpl for testing to be able to properly test all of their code. The lack of metis actually caused a configure error which was reported in ticket #1780...*Created by: bmpersc*
@trilinos/framework The @trilinos/shylu team needs metis to be a tpl for testing to be able to properly test all of their code. The lack of metis actually caused a configure error which was reported in ticket #1780. An immediate solution was to make the requirement of metis optional with the caveat that we would get a metis tpl setup so that we can eventually run the tests.
@trilinos/shylu can you provide the version of metis you would prefer to have available please? https://gitlab.osti.gov/jmwille/Trilinos/-/issues/4492Framework: Disable the non- dev->master PR tests in the Clean Track2019-02-25T17:28:41ZJames WillenbringFramework: Disable the non- dev->master PR tests in the Clean Track*Created by: william76*
Description
-----------
We've moved the develop -> master pull request jobs to report to the Clean track.
Since we are no longer using the old "Clean" jobs to determine the develop -> master merge, we should...*Created by: william76*
Description
-----------
We've moved the develop -> master pull request jobs to report to the Clean track.
Since we are no longer using the old "Clean" jobs to determine the develop -> master merge, we should remove them from the Clean track.
@jwillenbring I'm assuming you wanted me to remove these tests entirely since they're somewhat redundant with the PR testing for dev->master. If you would rather these be moved to the Nightly track instead, please let me know.
@trilinos/framework FYI
Task(s)
--------
- [x] Remove Linux-gcc-7.3.0-MPI_Release_gcc_7.3.0_openmpi_1.10.1_DEV
- [x] Remove Linux-gcc-4.8.4-MPI_Release_gcc_4.8.4_openmpi_1.10.1_DEV
https://gitlab.osti.gov/jmwille/Trilinos/-/issues/2423Framework: Add a GPU test into nightlies2019-02-25T17:12:06ZJames WillenbringFramework: Add a GPU test into nightlies*Created by: william76*
@trilinos/framework
Add GPU testing into a nightly build under the Experimental track to run on a testbed.
## Motivation and Context
Nightly tests currently don't run a GPU build consistently... we'd like...*Created by: william76*
@trilinos/framework
Add GPU testing into a nightly build under the Experimental track to run on a testbed.
## Motivation and Context
Nightly tests currently don't run a GPU build consistently... we'd like to move towards getting a GPU based test into the Nightly Clean track eventually and possibly even into the Pull Request test suite. The first step towards this is to work up a test in the Experimental track that can run the suite on a testbed machine with GPUs and get the errors cleaned up.
## Definition of Done
- [ ] Add GPU test on White (?)
@jwillenbring - per our discussion this morning, I'm adding the issue to track this.