Skip to content

Update and simplify NaN-safe mode instructions #747

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Update and simplify NaN-safe mode instructions #747

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6db10d9
Update and simplify NaN-safe mode instructions
devmotion Apr 13, 2025
fe02814
Fix typo
devmotion Apr 13, 2025
6127a6c
Update docs/src/user/advanced.md
devmotion Apr 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 7 additions & 13 deletions docs/src/user/advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,27 +149,21 @@ ForwardDiff's `NaN`-safe mode by using the
the `nansafe_mode` preference to true, for example via:

```julia
julia> using ForwardDiff, Preferences
julia> using Preferences

Copy link
Member

Choose a reason for hiding this comment

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

This is also necessary for it to work, I believe:

Suggested change
julia> import Pkg; Pkg.add("ForwardDiff")

Copy link
Member Author

Choose a reason for hiding this comment

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

Only if you don't have installed ForwardDiff yet. I (and the previous authors I suppose) assume that that's already case - given that this is the documentation of ForwardDiff, installation of ForwardDiff is the first thing you have to do if you want to follow or apply anything from the docs.

Copy link
Member

Choose a reason for hiding this comment

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

No, it's not enough to have ForwardDiff installed. It has to be specifically installed in this environment. Not just visible from a lower-level one.

Copy link
Member Author

Choose a reason for hiding this comment

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

Sure, that's what I assumed. Does anyone actually install ForwardDiff in e.g. the global environment? I assumed everyone working with the docs would have ForwardDiff installed in their current environment.

Copy link
Member

@mcabbott mcabbott Apr 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I do. But also, the obvious way to try out this thing is ] activate --temp, so that you can compare to your other session & not mess anything up. (Especially since there's no way to reverse this change clearly described.)

Why make instructions for which this fails? Why not make instructions which work when copy-pasted 100% of the time?

Copy link
Member Author

Choose a reason for hiding this comment

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

But also, the obvious way to try out this thing is ] activate --temp, so that you can compare to your other session & not mess anything up.

Exactly, and in that case everyone who wants to try something ForwardDiff-docs-related surely has installed ForwardDiff already in that temporary environment? That's at least my typical use case...

In any case, my intention was mostly to not clutter the docs with redundant information. We surely do not want to add Pkg.add("ForwardDiff") to every code block?

Copy link
Member

Choose a reason for hiding this comment

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

Exactly, and in that case everyone who wants to try something ForwardDiff-docs-related surely has installed

No, they made this environment 5 seconds ago, just before pasting in the presumably complete doc example. Which fails with a mysterious error, even though ForwardDiff can load just fine. You are really assuming everyone will be on your golden path here. And I am telling you experimentally that someone who knows a fair bit about these things was completely baffled by this not just working.

We surely do not want to add Pkg.add("ForwardDiff") to every code block?

Right. Normally you type in using ForwardDiff, and it either just works, or prompts you to install. It "just works" even if ForwardDiff is not in this specific environment, it only has to be visible from it.

julia> set_preferences!(ForwardDiff, "nansafe_mode" => true)
```

Note that Julia has to be restarted and ForwardDiff has to be reloaded after changing
this preference.

Alternatively, you can set the preference before loading ForwardDiff, for example via:

```julia
julia> using Preferences, UUIDs

julia> set_preferences!(UUID("f6369f11-7733-5829-9624-2563aa707210"), "nansafe_mode" => true)
julia> set_preferences!("ForwardDiff", "nansafe_mode" => true)

julia> using ForwardDiff

julia> log(ForwardDiff.Dual{:tag}(0.0, 0.0))
Dual{:tag}(-Inf,0.0)
```

!!! warn
The preference has to be set **before** loading ForwardDiff.
If you change it after loading ForwardDiff, you have to restart your Julia session (using the same environment)
and then reload ForwardDiff for it to become active.

In the future, we plan on allowing users and downstream library authors to dynamically
enable [`NaN`-safe mode via the `AbstractConfig`
API](https://github.com/JuliaDiff/ForwardDiff.jl/issues/181).
Expand Down
Loading