[Merged by Bors] - Add Exponential Moving Average into diagnostics

[CAD97]

Objective

• Add Time-Adjusted Rolling EMA-based smoothing to diagnostics.
• Closes Provide smoothed diagnostics readings #4983; see that issue for more more information.

Terms

• EMA - Exponential Moving Average
• SMA - Simple Moving Average

Solution

• We use a fairly standard approximation of a true EMA where $EMA_{\text{frame}} = EMA_{\text{previous}} + \alpha \left( x_{\text{frame}} - EMA_{\text{previous}} \right)$ where $\alpha = \Delta t / \tau$ and $\tau$ is an arbitrary smoothness factor. (See Provide smoothed diagnostics readings #4983 for more discussion of the math.)
• The smoothness factor is here defaulted to $2 / 21$; this was chosen fairly arbitrarily as supposedly related to the existing 20-bucket SMA.
• The smoothness factor can be set on a per-diagnostic basis via Diagnostic::with_smoothing_factor.

---

Changelog

Added

• Diagnostic::smoothed - provides an exponentially smoothed view of a recorded diagnostic, to e.g. reduce jitter in frametime readings.

Changed

• LogDiagnosticsPlugin now records the smoothed value rather than the raw value.
  • For diagnostics recorded less often than every 0.1 seconds, this change to defaults will have no visible effect.
  • For discrete diagnostics where this smoothing is not desirable, set a smoothing factor of 0 to disable smoothing.
  • The average of the recent history is still shown when available.

[CAD97]

I should note that due to exactly how diagnostics were calculated/tracked, the translation is for numerically (almost¹) equivalent now

before	after
diagnostics[FRAME_TIME].value()	diagnostics[FRAME_TIME].value()
diagnostics[FRAME_TIME].average()	diagnostics[FRAME_TIME].average()
(none)	diagnostics[FRAME_TIME].smoothed()
1 / diagnostics[FRAME_TIME].value()	diagnostics[FPS].value()
diagnostics[FPS].value() (is also)	diagnostics[FPS].average()
1 / diagnostics[FRAME_TIME].average()	diagnostics[FPS].average()
diagnostics[FPS].average()	(none)2
(none)	diagnostics[FPS].smoothed()

Footnotes

1. floats (aliens.png) ↩

2. If for some reason you do want the old FPS average³, this is achievable by averaging 20 frames worth of data of the new averaged FPS or FRAME_TIME. This is most simply done by recording a diagnostic with a 20-length history of 1 / diagnostics[FRAME_TIME].average() and taking its .average(); this is the old way that the FPS diagnostic was calculated. ↩

3. Perhaps for consistency of performance metrics over time? Though the engine update is likely to outweigh the impact of changing how the FPS diagnostic is recorded. ↩

[CAD97]

I went ahead and added per-diagnostic customization of the smoothing factor so it can be more easily tuned.

I will reiterate that the default factor of $2 / 21$ here is completely arbitrary, and it should ideally be tuned for each application. $0.1$ is a rather common starting point, so we're in good company, but the exact smoothing feel desired differs per developer, and the default should probably be chosen by someone more familiar with bevy.

Discrete diagnostic measurements like asset or entity count probably will want to use a smoothing factor of $0$ to disable smoothing, especially as this PR currently prints the smoothed diagnostic in LogDiagnosticPlugin. This will avoid smoothing these counts and presenting a fractional number of entities 🙃 I haven't done so yet to let the stakeholders here decide appropriate tuning for the smoothing factor(s).

[alice-i-cecile]

Yes please. This is well implemented. I like that you changed the examples to use this, and I appreciate that you can control the smoothing on a per-diagnostic basis.

[hymm]

I'm in favor of having this built in and using this in the examples.

[CAD97]

Rebased for the upstream changes. Note that #3871 already did the change from logging FPS as $1/SMA_\text{frametime}$ to just $1/\text{frametime}$, so this PR no longer contains that change.

[alice-i-cecile]

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-and-install-on-iOS
• build-android
• build (macos-latest)
• build (ubuntu-latest)
• build-wasm
• build (windows-latest)
• build-without-default-features (bevy)
• build-without-default-features (bevy_ecs)
• build-without-default-features (bevy_reflect)
• check-compiles
• check-doc
• check-missing-examples-in-docs
• ci
• markdownlint
• run-examples
• run-examples-on-wasm
• run-examples-on-windows-dx12

[DavidAntliff]

@CAD97 how do you anticipate the with_smoothing_factor() function to be used?

The following doesn't compile because the function takes ownership of self, but (as far as I'm aware) we can only get a reference to the Diagnostic object:

fn my_system(
    diagnostics: Res<DiagnosticsStore>,
) {
    let fps: &Diagnostic = diagnostics.get(&FrameTimeDiagnosticsPlugin::FPS).unwrap();
    let custom_smoothed_fps = fps.with_smoothing_factor(1.0);
    //                        ^^^ cannot move
}

Diagnostic doesn't implement Copy or Clone so I don't see a way to call this function without having ownership.

    #[must_use]
    pub fn with_smoothing_factor(mut self, smoothing_factor: f64) -> Self {
        self.ema_smoothing_factor = smoothing_factor;
        self
    }

Sadly, ema_smoothing_factor is private so it can't be set directly.

[CAD97]

@DavidAntliff like the other builder methods (e.g. with_suffix), it's to be used when creating the Diagnostics resource.

[DavidAntliff]

@CAD97 ah, so no intention to be able to modify the smoothing factor at an arbitrary point in time? Only at construction? I had hoped to be able to switch between a set of smoothing values in response to user input, but it seems I'll need to investigate whether a resource can be created (and the existing one replaced by it) by a System function.

[CAD97]

I don't immediately see any reason how changing the smoothing factor at runtime would be problematic, so adding a method to set it directly should be fine.

Until such is made available, &mut access can be used to mem::replace the diagnostic resource, either completely or temporarily (e.g. to call with_smoothing_factor and then place the resource back).