Move multicore calculation packages to suggests

[FrankvRaffe]

In case multicore calculations are not set to defaults (see issue #15), the imports of this package can be diminished substantially. Packages future.apply, progressr, future, and parallely all do not need to be directly imported.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Move four multicore packages (future, future.apply, parallelly, and progressr) from Imports to Suggests in DESCRIPTION, making them optional dependencies that are only required when users explicitly choose parallel processing strategies.

Observations

Codebase Summary

The rotsee package provides RothC soil carbon simulation capabilities. The rc_sim_multi() function in R/rc_sim_multi.R supports three execution strategies: "sequential" (default), "multicore", and "multisession". Currently, all four multicore packages are hard dependencies in Imports, but they're only needed when using parallel strategies. The code already uses namespace-qualified function calls, making it well-suited for optional dependencies.

Assumptions

Assumption 1: When should multicore packages be required?

Options Considered:

• Require packages when any strategy parameter is set (including sequential)
• Require packages only when parallel strategies ("multicore" or "multisession") are selected
• Always silently fall back to sequential if packages unavailable

Chosen Option: Require packages only for parallel strategies ("multicore" or "multisession")

Rationale: This provides the best developer experience by avoiding unnecessary installations while giving clear error messages when parallel features are requested but packages aren't available. The sequential strategy can function without any multicore packages.

Assumption 2: How should progressr be handled?

Options Considered:

• Keep progressr in Imports since it's used regardless of strategy
• Make progressr optional and skip progress tracking if unavailable
• Only use progressr when parallel strategies are active

Chosen Option: Make progressr completely optional for all strategies

Rationale: Progress tracking is a nice-to-have UX feature but not essential functionality. Since the default is quiet=TRUE (no progress display), most users won't notice if progressr is absent. This aligns with the goal of reducing unnecessary dependencies.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Refactor Package Availability Checks

Modify the package checking logic in rc_sim_multi() to make dependencies conditional based on the selected execution strategy.

Task 1: Make Multicore Package Checks Conditional

Update the package availability checks in R/rc_sim_multi.R to only require future, future.apply, and parallelly when strategy is "multicore" or "multisession".

• Replace the unconditional system.file() checks at lines 42-44 with conditional logic that checks strategy %in% c("multicore", "multisession")
• Use requireNamespace() instead of system.file() for more idiomatic R package checking
• Update error messages to clarify which packages are needed for parallel strategies
• Error messages should guide users to install packages with: install.packages(c("future", "future.apply", "parallelly"))

Task 2: Make progressr Optional

Wrap progressr usage in conditional checks to make progress tracking optional.

• Before calling progressr::with_progress() at line 92, check if progressr is available using requireNamespace("progressr", quietly = TRUE)
• If progressr is available, use the existing progressr::with_progress() wrapper
• If progressr is not available, skip the progress wrapper and call future.apply::future_lapply() directly
• The conditional progressor creation at line 94 (based on quiet parameter) should remain, nested within the progressr availability check
• This ensures the function works with or without progressr installed

Task 3: Update Core Detection Logic

Ensure the parallelly::availableCores() calls are only executed when the package is available.

• The core detection logic at lines 62, 78, and 81 should only run when strategy requires parallel processing
• For sequential strategy with cores parameter specified, ignore the parameter (sequential doesn't use multiple cores anyway)
• Consider adding a warning if user specifies cores parameter with sequential strategy

🤖 Prompt for AI agents

Refactor `rc_sim_multi()` to make multicore packages conditional based on
execution strategy.

For parallel strategies ("multicore" or "multisession"):
- Add conditional check: `if (strategy %in% c("multicore", "multisession"))`
- Use `requireNamespace()` to check for future, future.apply, and parallelly
packages
- Provide clear error messages with installation instructions if packages are
missing
- Only execute core detection logic when parallel processing is required

For progressr:
- Wrap `progressr::with_progress()` usage in `requireNamespace("progressr",
quietly = TRUE)` check
- If progressr is available, use the progress wrapper
- If not available, call `future.apply::future_lapply()` directly without
progress tracking

For sequential strategy:
- Allow execution without any multicore packages
- Ignore cores parameter if specified
- Add warning if cores parameter is used with sequential strategy

Phase 2: Update Package Metadata and Namespace

Move the four packages from required to suggested dependencies and regenerate the namespace.

Task 1: Update DESCRIPTION File

Modify the package dependency declarations.

• Move future, future.apply, parallelly, and progressr from the Imports field to the Suggests field in DESCRIPTION
• Maintain the existing Suggests packages (devtools, usethis, testthat, knitr, rmarkdown, patchwork, roxygen2)
• Preserve version requirements if any exist for these packages

Task 2: Update Roxygen Documentation Tags

Remove the import declarations from the roxygen comments in R/rc_sim_multi.R.

• Remove or comment out the @import future tag at line 19
• Remove or comment out the @import future.apply tag at line 20
• Remove or comment out the @import parallelly tag at line 21
• Remove or comment out the @import progressr tag (location from findings)
• The namespace-qualified function calls (e.g., future::plan()) will continue to work without import statements

Task 3: Regenerate NAMESPACE

Run roxygen to update the NAMESPACE file.

• Execute roxygen2::roxygenize() or equivalent to regenerate NAMESPACE
• Verify that the import(future), import(future.apply), import(parallelly), and import(progressr) statements are removed
• The NAMESPACE should retain imports for other packages (checkmate, data.table, ggplot2, deSolve)

🤖 Prompt for AI agents

Update package metadata to move multicore packages to optional dependencies.

In DESCRIPTION:
- Move future, future.apply, parallelly, and progressr from Imports to Suggests
- Keep existing Suggests packages
- Preserve any version requirements

In R/rc_sim_multi.R:
- Remove @import tags for future, future.apply, parallelly, and progressr
- Keep namespace-qualified function calls (e.g., `future::plan()`)

Regenerate NAMESPACE:
- Run `roxygen2::roxygenize()` to update NAMESPACE file
- Verify removal of import statements for the four packages
- Ensure other package imports remain intact

Phase 3: Update Documentation and Examples

Enhance the user-facing documentation to clarify when optional packages are needed.

Task 1: Update Function Documentation

Revise the @description and parameter documentation in R/rc_sim_multi.R.

• Update the @description section to clarify that parallel strategies require additional packages
• Add a note to the @param strategy documentation indicating that "multicore" and "multisession" require installing future, future.apply, and parallelly packages
• Add a note to the @param quiet documentation that progressr package enables progress tracking functionality
• Consider adding a @details section explaining the optional dependencies and how to install them

Task 2: Add Usage Examples

Add examples to the function documentation showing both basic and parallel usage.

• Add an @examples section to rc_sim_multi.R if one doesn't exist
• Include a basic example using the default sequential strategy (works without optional packages)
• Include a commented example showing how to enable parallel processing with strategy="multisession"
• Add a comment showing the installation command for optional packages: install.packages(c("future", "future.apply", "parallelly", "progressr"))

🤖 Prompt for AI agents

Update documentation to inform users about optional multicore dependencies.

In function documentation:
- Update @description to mention parallel strategies require additional packages
- Add note to @param strategy explaining "multicore" and "multisession" require
future, future.apply, and parallelly
- Add note to @param quiet explaining progressr enables progress tracking
- Add @details section explaining optional dependencies and installation

In examples:
- Add @examples section if missing
- Include basic sequential strategy example (no optional packages needed)
- Add commented example for parallel processing with strategy="multisession"
- Include installation command comment: `install.packages(c("future",
"future.apply", "parallelly", "progressr"))`

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Refactor `rc_sim_multi()` to make multicore packages conditional based on
execution strategy.

For parallel strategies ("multicore" or "multisession"):
- Add conditional check: `if (strategy %in% c("multicore", "multisession"))`
- Use `requireNamespace()` to check for future, future.apply, and parallelly
packages
- Provide clear error messages with installation instructions if packages are
missing
- Only execute core detection logic when parallel processing is required

For progressr:
- Wrap `progressr::with_progress()` usage in `requireNamespace("progressr",
quietly = TRUE)` check
- If progressr is available, use the progress wrapper
- If not available, call `future.apply::future_lapply()` directly without
progress tracking

For sequential strategy:
- Allow execution without any multicore packages
- Ignore cores parameter if specified
- Add warning if cores parameter is used with sequential strategy
===============================================================================

Task: 2

Update package metadata to move multicore packages to optional dependencies.

In DESCRIPTION:
- Move future, future.apply, parallelly, and progressr from Imports to Suggests
- Keep existing Suggests packages
- Preserve any version requirements

In R/rc_sim_multi.R:
- Remove @import tags for future, future.apply, parallelly, and progressr
- Keep namespace-qualified function calls (e.g., `future::plan()`)

Regenerate NAMESPACE:
- Run `roxygen2::roxygenize()` to update NAMESPACE file
- Verify removal of import statements for the four packages
- Ensure other package imports remain intact
===============================================================================

Task: 3

Update documentation to inform users about optional multicore dependencies.

In function documentation:
- Update @description to mention parallel strategies require additional packages
- Add note to @param strategy explaining "multicore" and "multisession" require
future, future.apply, and parallelly
- Add note to @param quiet explaining progressr enables progress tracking
- Add @details section explaining optional dependencies and installation

In examples:
- Add @examples section if missing
- Include basic sequential strategy example (no optional packages needed)
- Add commented example for parallel processing with strategy="multisession"
- Include installation command comment: `install.packages(c("future",
"future.apply", "parallelly", "progressr"))`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!