[Documentation] The tmpdir_stagger_phase_ options are very hard to understand

I had been trying a lot of things with tmpdir_stagger_phase_ before finally understanding them thanks to @jkbecker in chat . In my case, they allow me to do what I want, but I had no idea they did.

There’s a few reasons why they are confusing to me:

• The documentation and the tool itself uses : to separate major minor, but the comment just says before tmpdir_stagger_phase_major tmpdir_stagger_phase_minor is less which is confusing.
• They are based around “tmpdir”, but i my case I have a single temp dir, and I am really only thinking about avoiding overloading my CPU, so it wasn’t intuitive that it could do what I want (why is phase limit per tmpdir?)
• The default of 1 seems very conservative, perhaps this is because it makes sense for people with many temp drives, but for people like me with a single temp drive, wouldn’t something like 4 here be a better default?
• the tmpdir_stagger_phase_major tmpdir_stagger_phase_minor are defined as the start of the next point beyond the limited window, this is a bit strange to wrap ones head around. EG if i want to limit what’s in phase 1, I set it to 2:1. Perfectly fine once I understand it, but didn’t lead to an intuitive reading.
• The monitored/limited window always starts with 0:0 (because plotman can’t predict when a job will enter a non 0:0 window start) but that isn’t really clear
• Given the way the major phases work (that they are intensive in different ways), is there any legitimate reason to tune the phase_minor here? Minor is always just the table. I feel like the inclusion of it makes it seem more complex and harder to understand
• I feel like the other options in the scheduling section are more intuitive and important, perhaps they come first, and this optional phase staggering is commented out and only used by people who wrap their head around it.
• tmpdir_stagger_phase_limit is marked as optional, but tmpdir_stagger_phase_x are not, which makes me think they work independently?

I think that in the long run the option names could be changed, or the whole stagger limit by phase window could be reconsidered, (for instance simply a phase_1_max_jobs option would be so clear), I think updating the comments in the default yaml file will help a lot. To kickstart the discussion I’ve quickly come up with the following draft.

[thomann061]

# Temporary Drive Plotter Phase Settings

# Because Chia Phase 1 utilizes more memory and cpu (thread) resources
# AND is the only multi-threaded stage (after phase 1, the jobs are single threaded)
# These phase settings can help fine tune your chia plotting process
# beyond setting a stagger or limit on number of concurrent jobs

# There are 3 parameters that will help you achieve this. But before learning those,
# take a look at the table below, to learn all the phases and steps of the chia plotting process

# Chia Phase:Step Table

# Phase	Step	% Progress
# 1	1	1%
# 1	2	6%
# 1	3	12%
# 1	4	20%
# 1	5	28%
# 1	6	36%
# 1	7	42%

# 2	1	43%
# 2	2	48%
# 2	3	51%
# 2	4	55%
# 2	5	58%
# 2	6	61%

# 3	1	66%
# 3	2	73%
# 3	3	79%
# 3	4	85%
# 3	5	92%
# 3	6	98%

# 4	1	100%

# Example 1 - Detailed Explanation

# The tmpdir_stagger_phase_major and tmpdir_stagger_phase_minor correspond
# to the phase and step the plotting process is currently in
# For e.g. it could be 2:1 (2 is the phase or major, 1 is the step or minor)
tmpdir_stagger_phase_major = 2		# phase 2
tmpdir_stagger_phase_minor = 1		# step 1

# The tmpdir_stagger_phase_limit corresponds to the number of plot jobs that can be
# concurrently run before reaching phase 2, step 1 or 2:1
# If this is set to 2, then there will always be 2 plot jobs
# concurrently ran during phase 1. Or specifically during (1:1, 1:2, 1:3, 1:4, 1:5, 1:6, 1:7)
tmpdir_stagger_phase_limit = 2		# limit of 2 plot jobs

# Example 2
# You may decide you want to allow 3 conconcurrent plot jobs to run during phase 1
# Increase the tmpdir_stagger_phase_limit to 3
# tmpdir_stagger_phase_major = 2	# phase 2
# tmpdir_stagger_phase_minor = 1	# step 1
# tmpdir_stagger_phase_limit = 3	# limit of 3 plot jobs

# Example 3
# You may decide you want to relax the restriction and expand the phase:step to 3:1
# And Increase the limit on jobs to 4
# tmpdir_stagger_phase_major = 3	# phase 3
# tmpdir_stagger_phase_minor = 1	# step 1
# tmpdir_stagger_phase_limit = 4	# limit of 4 plot jobs

[graemes]

Perhaps a better term might be _phase pair _ (or at least that’s how I think of it). From https://github.com/Chia-Network/chia-blockchain/wiki/Beginners-Guide - There are 4 phases that does operations in 7 tables

A table (phase) pair is Phase (major) and Step (minor).