Update Tutorials #26

jClugstor · 2025-09-28T20:14:49Z

Checklist

Appropriate tests were added
Any code changes were done in a way that does not break public API
All documentation related to code changes were updated
The new code follows the
contributor guidelines, in particular the SciML Style Guide and
COLPRAC.
Any new documentation only uses public API

Additional context

Add any other context about the problem here.

jClugstor · 2025-09-28T20:15:20Z

@ChrisRackauckas I think these are better

ChrisRackauckas · 2025-09-28T20:19:15Z

docs/src/developer_tutorial.md

+3.  Log levels - Predefined log levels (`Silent`, `InfoLevel`, `WarnLevel`, `ErrorLevel`, `CustomLevel(n)`)
+4.  Verbosity preset levels - `None`, `Minimal`, `Standard`, `Detailed`, `All`
+


Explain this a bit. It sounds redundant without more information. What happens if you use both? Etc.

ChrisRackauckas · 2025-09-28T20:19:59Z

docs/src/developer_tutorial.md

+- Type parameter T: Controls whether logging is enabled (T=true) or disabled (T=false). When `T = false`, any use of the `SciMLLogging.emit_message` function points to any empty function. When the the type parameter is known at compile time, this allows for the compiler to make certain optimizations that can lead to this system having zero runtime overhead when not in use. 
+- Message levels: Fields of the `AbstractVerbositySpecifier` represent messages or groups of messages. These fields should be of the type `SciMLLogging.MessageLevel`. Each message level subtype represents a different level at which the message will be logged at. 
+### @SciMLMessage 


This doesn't make sense. Can you share an example?

ChrisRackauckas · 2025-09-28T20:22:20Z

docs/src/developer_tutorial.md

 ```

-This example shows the minimal structure needed to integrate SciMLLogging into a package.
+This example shows the minimal structure needed to integrate SciMLLogging into a package.


The tutorial starts here? Why is there effectively a manual page on the top of the tutorial? Why isn't there a manual page for the manual page information?

ChrisRackauckas · 2025-09-28T20:23:13Z

docs/src/developer_tutorial.md

-This example shows the minimal structure needed to integrate SciMLLogging into a package.
+This example shows the minimal structure needed to integrate SciMLLogging into a package.
+
+## Utility Functions for Integration


This is manual page information... why is this here??????

Yeah, I'll set up a separate manual page and put this stuff there.

ChrisRackauckas · 2025-09-28T20:23:41Z

docs/src/developer_tutorial.md

+### `verbosity_to_int()`
+
+Converts a `MessageLevel` to an integer value. This is useful when interfacing with packages that use integer-based verbosity levels:


This is docstring information. Why is it not in a docstring?

It's in the docstring for verbosity_to_int

Then why is it copied? You already violated the standard style by just making an API page, instead there just needs to be a manual page where the right docstrings have the right information around it, rather than just dumping docstrings in a random order with no context.

I didn't create the api.md file, that was Claude c147cab

I'll take a look at the Documentation part of the SciML style guide and fix these up

ChrisRackauckas · 2025-09-28T20:25:17Z

docs/src/user_tutorial.md

- **`T` parameter**: Controls whether logging is enabled (`T=true`) or disabled (`T=false`)
- **Each field**: Represents a category of messages the package can emit
- **MessageLevel values**: Can be `Silent()`, `InfoLevel()`, `WarnLevel()`, `ErrorLevel()`, or `CustomLevel(n)` for custom levels
+- **`T` parameter**: Controls whether logging is enabled (`T=true`) or disabled (`T=false`) for all messages


Why is there a T if there's also the message levels? Why wouldn't you just construct with all Silent?

Having the T there allowed the actual construction of the LinearVerbosity object to be compiled out in earlier iterations. Moving to the types for all of the levels seems to have broken that but I thought it might be useful to keep around in case I can get that working again.

It's not strictly necessary to make it work, so I could get rid of it.

ChrisRackauckas · 2025-09-28T20:28:26Z

docs/src/user_tutorial.md

+    - `Silent()` : no message is emitted
+    - `InfoLevel()` : message is emitted as an `Info` log
+    - `WarnLevel()` : message is emitted as a `Warn` log
+    - `ErrorLevel()` : message is emitted as an `Error` log
+    - `CustomLevel(n)` : message is emitted at `LogLevel(n)`


Are these types? How does ::MessageLevel work then? Don't those all have to be MessageLevel?

Oh... this is misnamed... https://github.com/SciML/SciMLLogging.jl/blob/main/src/verbosity.jl#L13 this kind of stuff really shouldn't need iterations.

Misnamed how exactly?

AbstractMessageLevel

ChrisRackauckas · 2025-09-28T20:29:50Z

docs/src/user_tutorial.md

    initialization::MessageLevel    # Controls startup messages
    iterations::MessageLevel        # Controls per-iteration output
    convergence::MessageLevel       # Controls convergence messages
-    warnings::MessageLevel          # Controls warning messages
+    error_control::MessageLevel     # Controls messages about solver error 


Won't this be uninferred?

Possibly since MessageLevel is an abstract type. I had no issues when testing LinearVerbosity with it set up like this though, JET tests pass etc. though we can change it to be all concrete and maybe we should.

Really this is up to whoever is implementing the AbstractVerbositySpecifier, the fields just need to be <: MessageLevel to be compatible with the macro.

It should probably be made concrete though, otherwise it won't compile out.

The logging code can still be compiled out when Silent() is used, even if they aren't concrete, I show it here: SciML/LinearSolve.jl#756 (comment)

But yeah only reason not to make it concrete is to be able to change logging levels with setproperty!, which was a request someone had. But that's not really that important

No supporting setproperty with this is a bad idea.

ChrisRackauckas · 2025-09-28T20:30:46Z

docs/src/user_tutorial.md

+    - `ErrorLevel()` : message is emitted as an `Error` log
+    - `CustomLevel(n)` : message is emitted at `LogLevel(n)`

 When `T=false`, all logging is disabled with zero runtime overhead. When `T=true`, each category can be individually controlled.


Why does this exist if there are presets?

ChrisRackauckas · 2025-09-28T20:35:37Z

docs/src/user_tutorial.md


-Here's an example of how one might use a packages `AbstractVerbositySpecifier` implementation to control the output.
-
+Here's an example of how one might use a packages `AbstractVerbositySpecifier` implementation to control the output, using the same `SolverVerbosity` type as above. 


Wouldn't the main way people use this be via Presets? So why are the details coming before the simple use case?

ChrisRackauckas · 2025-09-28T20:37:24Z

docs/src/user_tutorial.md

+Note: You need to restart Julia after changing the backend preference in order to use the chosen backend.
+
+
 ## Common Scenarios


This section is just redundant information.

jClugstor · 2025-09-29T22:12:39Z

Added manual page with docstrings for every feature of the package
streamlined the getting started page
made the tutorials less verbose, included some actual runnable examples
@ChrisRackauckas does this look better?

ChrisRackauckas · 2025-10-02T08:58:04Z

docs/src/getting_started.md

+
+**Available Presets:**
+- `None()`: No output at all (zero overhead)
+- `Minimal()`: Only essential messages and warnings
+- `Standard()`: Balanced verbosity for typical usage
+- `Detailed()`: Comprehensive information for debugging
+- `All()`: Maximum verbosity


Suggested change

**Available Presets:**

- `None()`: No output at all (zero overhead)

- `Minimal()`: Only essential messages and warnings

- `Standard()`: Balanced verbosity for typical usage

- `Detailed()`: Comprehensive information for debugging

- `All()`: Maximum verbosity

jClugstor · 2025-10-07T19:01:56Z

@ChrisRackauckas anything else?

ChrisRackauckas · 2025-10-09T09:05:35Z

It's still missing the main manual page.

ChrisRackauckas · 2025-10-10T09:14:52Z

docs/src/manual/presets.md

+
+Use `Minimal` when you want to be informed of important issues but don't need detailed progress information.
+
+**What to include at each level:**


Suggested change

**What to include at each level:**

**What to include at this level:**

ChrisRackauckas · 2025-10-10T09:15:08Z

docs/src/manual/presets.md

+**Typical message categories:**
+- Errors: `ErrorLevel()`
+- Warnings: `WarnLevel()`
+- Everything else: `Silent()`


What does this mean?

This part is meant more for the people implementing the presets. I wanted to give a rough idea of what log levels should be included each preset, and what should be silent.

So for the Minimal preset, you would only want errors and warnings to show up in the logs, and you would want to log them at the error level and the warning level. Then all other informational things should be silent.

Yes I know that's what it's for, but it's not understandable. Why not just write a normal sentence?

ChrisRackauckas · 2025-10-10T09:15:34Z

docs/src/manual/presets.md

+Use `Minimal` when you want to be informed of important issues but don't need detailed progress information.
+
+**What to include at each level:**
+- **WarnLevel or higher**: Warnings about potential issues (e.g., convergence problems, parameter choices that may affect results, deprecated features)


Should this be here?

Is it better if this kind of stuff is in the docstrings for each preset?

ChrisRackauckas · 2025-10-10T09:15:49Z

docs/src/manual/presets.md

+
+**What to include at each level:**
+- **WarnLevel or higher**: Warnings about potential issues (e.g., convergence problems, parameter choices that may affect results, deprecated features)
+- **ErrorLevel**: Critical failures and errors that stop computation


Is this true?

I think so? What else would we want to use ErrorLevel for?

ChrisRackauckas · 2025-10-10T09:16:19Z

docs/src/manual/presets.md

+- **InfoLevel or higher**: Important initialization messages (e.g., algorithm selection, key parameter values), significant milestones, convergence status, final results, warnings, and errors
+- **WarnLevel or higher**: All warnings and errors as in `Minimal`
+- **ErrorLevel**: All critical failures


Copied? Is there a reason to not just say it has all of below and?

ChrisRackauckas · 2025-10-10T09:17:16Z

It is completely not understandable what should be in each level. Try again. Is that Claude because it's really bad? This is really wasting time to have me review your Claude output without you ever reading it.

jClugstor · 2025-10-10T15:56:40Z

Not trying to waste your time. These made sense in my head, good to know they were confusing.

I moved the descriptions of what each preset should have in to the docstrings, and made them read more like a sentence. Hopefully they make more sense now.

Also let me know your opinion on #29. If we want ErrorLevel to throw an error that of course should be documented as well.

ChrisRackauckas · 2025-10-13T12:34:31Z

docs/src/manual/presets.md

Needs examples of what kinds of things would go into each category.

ChrisRackauckas · 2025-10-13T12:35:55Z

docs/src/manual/presets.md


-The `All` preset enables maximum verbosity, useful for deep debugging or understanding complex behaviors.
-
 ## Custom Presets


How does this work? It doesn't dispatch?

ChrisRackauckas · 2025-10-13T12:37:23Z

src/verbosity.jl

+
+This verbosity preset should include the settings from `Minimal`, while also setting 
+messages such as important initialization messages (e.g., algorithm selection, key parameter values), 
+significant milestones, convergence status, final results to `InfoLevel()` or higher.


what do you mean by significant milestones?

ChrisRackauckas · 2025-10-13T12:38:14Z

src/verbosity.jl

+(e.g., iteration counters, intermediate state), performance metrics 
+(e.g., timing information, memory usage), detailed diagnostics, and internal state information.
+The only messages that should be `Silent()` at this preset are very small details that would 
+clutter output even during debugging. 


Suggested change

clutter output even during debugging.

clutter output even during debugging and outputs that require a significant amount of additional computation

(for example, computing condition numbers of matrices which are normally not computed during the standard

usage).

ChrisRackauckas · 2025-10-13T12:40:59Z

src/verbosity.jl

+
+This verbosity preset should set messages related to critical failures and 
+errors that stop computation to `ErrorLevel`. Messages related to potential issues 
+(e.g., convergence problems, parameter choices that may affect results, deprecated features)


Suggested change

(e.g., convergence problems, parameter choices that may affect results, deprecated features)

(e.g., convergence problems, solver exiting, etc.)

ChrisRackauckas · 2025-10-13T12:41:33Z

src/verbosity.jl

+This verbosity preset should include the settings from `Minimal`, while also setting 
+messages such as important initialization messages (e.g., algorithm selection, key parameter values), 
+significant milestones, convergence status, final results to `InfoLevel()` or higher.
 """


Suggested change

"""

Deprecation warnings should be included at `WarnLevel()`. Critical but non-fatal warnings, such as

major performance warnings about fallbacks related to a given problem/solver choice, should be

included at this level.

"""

ChrisRackauckas · 2025-10-13T12:41:57Z

src/verbosity.jl

 the user with details.
+
+This verbosity preset should include the settings from `Minimal`, while also setting 
+messages such as important initialization messages (e.g., algorithm selection, key parameter values), 


No, we shouldn't print algorithm selection by default or key parameter values... that would be really noisy. We don't do that standard so why would we change that?

ChrisRackauckas · 2025-10-13T13:27:42Z

What are the message levels and why aren't they 1-1 with presets?

Why are they using names @info, @warn, etc., are they redirecting the output to different logging forms or are they for levels? That makes no sense.

ChrisRackauckas · 2025-10-13T13:28:00Z

I will merge so it has my updates, but there are still a lot of nonsensical things in here.

ChrisRackauckas reviewed Sep 28, 2025

View reviewed changes

jClugstor force-pushed the tutorial_updates branch from 87dad2c to 924ee09 Compare September 29, 2025 00:59

jClugstor added 13 commits September 29, 2025 18:03

remove extra tutorial

6f28a22

update user_tutorial

1280e33

update developer tutorial

0cdeb2f

fix line

200e8fe

rename VerbosityPreset to AbstractVerbosityPreset

335c2af

add manual pages

b202d6b

remove api.md, move tutorials

0df9317

add getting_started, update pages

27fccab

fix pages

54ccf1c

exports, fix up docs

d554e34

more doc fixes

16bdfca

fix local links

5b5d186

fix crossreferences

fc6397c

jClugstor force-pushed the tutorial_updates branch 2 times, most recently from ec79818 to fc6397c Compare September 29, 2025 22:07

ChrisRackauckas reviewed Oct 2, 2025

View reviewed changes

jClugstor requested a review from ChrisRackauckas October 7, 2025 19:01

rename files, add descriptions

12a9e14

jClugstor added 2 commits October 9, 2025 10:01

remove line

35184b7

fix pages

4618f8a

jClugstor force-pushed the tutorial_updates branch from bbf0bbc to 4618f8a Compare October 9, 2025 15:33

ChrisRackauckas reviewed Oct 10, 2025

View reviewed changes

get rid of clutter, improve docstrings for presets

970fb94

ChrisRackauckas reviewed Oct 13, 2025

View reviewed changes

docs/src/manual/presets.md

Copy link

Member

ChrisRackauckas Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs examples of what kinds of things would go into each category.

Update presets.md

01a6024

ChrisRackauckas reviewed Oct 13, 2025

View reviewed changes

ChrisRackauckas added 4 commits October 13, 2025 09:11

Update presets.md

46a5604

Update verbosity.jl

223a6d2

Merge branch 'main' into tutorial_updates

b1dd74b

Update message_levels.md

315d265

ChrisRackauckas merged commit bec0247 into SciML:main Oct 13, 2025
4 checks passed

		3. Log levels - Predefined log levels (`Silent`, `InfoLevel`, `WarnLevel`, `ErrorLevel`, `CustomLevel(n)`)
		4. Verbosity preset levels - `None`, `Minimal`, `Standard`, `Detailed`, `All`

		### `verbosity_to_int()`

		Converts a `MessageLevel` to an integer value. This is useful when interfacing with packages that use integer-based verbosity levels:


		Here's an example of how one might use a packages `AbstractVerbositySpecifier` implementation to control the output.

		Here's an example of how one might use a packages `AbstractVerbositySpecifier` implementation to control the output, using the same `SolverVerbosity` type as above.

		Note: You need to restart Julia after changing the backend preference in order to use the chosen backend.


		## Common Scenarios


		Use `Minimal` when you want to be informed of important issues but don't need detailed progress information.

		What to include at each level:

	What to include at each level:
	What to include at this level:


		The `All` preset enables maximum verbosity, useful for deep debugging or understanding complex behaviors.

		## Custom Presets

-clutter output even during debugging.
+clutter output even during debugging and outputs that require a significant amount of additional computation
+(for example, computing condition numbers of matrices which are normally not computed during the standard
+usage).

	(e.g., convergence problems, parameter choices that may affect results, deprecated features)
	(e.g., convergence problems, solver exiting, etc.)

-"""
+Deprecation warnings should be included at `WarnLevel()`. Critical but non-fatal warnings, such as
+major performance warnings about fallbacks related to a given problem/solver choice, should be
+included at this level.
+"""

Uh oh!

Update Tutorials #26

Update Tutorials #26

Uh oh!

Conversation

jClugstor commented Sep 28, 2025

Checklist

Additional context

Uh oh!

jClugstor commented Sep 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jClugstor commented Sep 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jClugstor commented Oct 7, 2025

Uh oh!

ChrisRackauckas commented Oct 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

ChrisRackauckas Oct 13, 2025 •

edited

Loading