Feature testing: Z-axis input shaper

[dmbutyugin]

Hi all,

I have implemented input shaper support for Z axis. This includes both input shaper itself, which can be configured as

[input_shaper]
shaper_type_z: mzv
shaper_freq_z: 50

and via SET_INPUT_SHAPER SHAPER_TYPE_Z=MZV SHAPER_FREQ_Z=50, and also resonance testing for it. The idea was circulating around way before, but the concern was how to tune it. However, it seems that the new resonance test that was introduced last year works OK for Z axis too. This allowed me to put this implementation together.

Now I’d like to invite interested testers to try it out. If the performance is good, I think it can be merged into the mainline Klipper. This new code is available in this branch and can be fetched via KIAUH by configuring it as

dmbutyugin/klipper,input-shaper-z

In order to test it, you’d need first to calibrate the input shaper. First, you’ll need to have an accelerometer mounted (and configured in printer.cfg) on the moving parts of Z axis - either the bed itself (if the bed moves over Z axis), or the toolhead (if the toolhead/gantry moves over Z). Make sure to add it to [resonance_tester] section:

[resonance_tester]
accel_chip_z: <accelerometer full chip name>

Then run a command

TEST_RESONANCES AXIS=Z OUTPUT=raw_data

And then run the calibration script as

~/klipper/scripts/calibrate_shaper.py /tmp/<filename>.csv -o ~/shaper_z.png

You can then put one of the recommendations into the input shaper config section. I would also appreciate if you could post the generated png and csv files here too to obtain some real-life data.

Notably, I tried to come up with default parameters for testing resonances over axis Z that should hopefully work for the majority of the users, but that requires testing in itself. The parameters for Z testing (with their current defaults) are

[resonance_tester]
max_freq_z: # 100 by default
accel_per_hz: # 12.5 by default
sweeping_accel_z: # 50 by default
accel_chip_z:  # no default; if unset, must be provided in CHIPS=<..> parameter

They can be overridden if necessary, but please try with the default settings first. They are much less aggressive compared to X/Y axes, and I’d like to understand whether they are enough or not.

Note that the default parameters require that maximum z velocity and accelerations are not smaller than certain values. If you have lower limits, TEST_RESONANCES will report an error and instruct to raise them. With the default test parameters you need to increase the limits to at least

[printer]
max_z_velocity: 20
max_z_accel: 1300

but only for the duration of the test, afterwards you can decrease them back if necessary. And if you use custom parameters, TEST_RESONANCES will provide the minimum required limits if necessary for your specific case.

Now, who could benefit from this new feature? Well, honestly, I do not expect that this will improve print quality by itself. However, users of delta printers or printers with flying gantry will be able to increase the max_z_accel and max_z_velocity and thus get faster Z movements (can be especially useful e.g. for toolchangers). Then, if you are using Z-hop (especially now that there is a ramping Z-hop feature available in many slicers), this new Z input shaper can improve the smoothness of Z axis operation, which you may be able to hear, and perhaps use more aggressive Z-hops that could result in less stringing.

I have tested resonances on a couple of my printers with the following results (first - heavy moving bed, second - ender 3 with the direct drive extruder):

FWIW, I went with more aggressive than the ‘best’ recommendations by the script in both cases - MZV 49 Hz in the first case, and 2HUMP_EI 62 Hz in the second one.

[LifeOfBrian]

Great feature!

Do you maybe have a before and after photo of a print with Z axis artefacts that the input shaper fixed?

[dmbutyugin]

Well, as I mentioned in my post, I do not expect that print quality itself will improve substantially, unlike with X/Y shapers. And I did not observe quality improvements in my prints, at least. However, previously ramping z-hops on my printer with the heavy bed sounded a bit like hammering (with each z-hop), and with this change z-hops sound much smoother, if audible at all, so at least there’s that.

[nefelim4ag]

Old EI, graph/output

Fitted shaper 'zv' frequency = 36.8 Hz (vibrations = 1.0%, smoothing ~= 0.117)
To avoid too much smoothing with 'zv', suggested max_accel <= 5200 mm/sec^2
Fitted shaper 'mzv' frequency = 37.6 Hz (vibrations = 0.0%, smoothing ~= 0.144)
To avoid too much smoothing with 'mzv', suggested max_accel <= 4200 mm/sec^2
Fitted shaper 'ei' frequency = 45.0 Hz (vibrations = 0.0%, smoothing ~= 0.159)
To avoid too much smoothing with 'ei', suggested max_accel <= 3800 mm/sec^2
Fitted shaper '2hump_ei' frequency = 56.0 Hz (vibrations = 0.0%, smoothing ~= 0.172)
To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3500 mm/sec^2
Fitted shaper '3hump_ei' frequency = 67.4 Hz (vibrations = 0.0%, smoothing ~= 0.180)
To avoid too much smoothing with '3hump_ei', suggested max_accel <= 3300 mm/sec^2
Recommended shaper is zv @ 36.8 Hz

New EI, graph/output

PR: input_shaper: Updated definitions of *EI input shapers by dmbutyugin · Pull Request #7048 · Klipper3d/klipper · GitHub
Look at the EI, 2HUMP_EI, 3HUMP_EI difference.

Fitted shaper 'zv' frequency = 36.8 Hz (vibrations = 1.0%, smoothing ~= 0.117)
To avoid too much smoothing with 'zv', suggested max_accel <= 5200 mm/sec^2
Fitted shaper 'mzv' frequency = 37.6 Hz (vibrations = 0.0%, smoothing ~= 0.144)
To avoid too much smoothing with 'mzv', suggested max_accel <= 4200 mm/sec^2
Fitted shaper 'ei' frequency = 46.2 Hz (vibrations = 0.0%, smoothing ~= 0.154)
To avoid too much smoothing with 'ei', suggested max_accel <= 3900 mm/sec^2
Fitted shaper '2hump_ei' frequency = 59.4 Hz (vibrations = 0.0%, smoothing ~= 0.160)
To avoid too much smoothing with '2hump_ei', suggested max_accel <= 3700 mm/sec^2
Fitted shaper '3hump_ei' frequency = 73.0 Hz (vibrations = 0.0%, smoothing ~= 0.167)
To avoid too much smoothing with '3hump_ei', suggested max_accel <= 3600 mm/sec^2
Recommended shaper is zv @ 36.8 Hz

My Z is in stealthChop.
Without input_shaper, there is a dull sound on the Z stop, with the shaper, there is no such sound.
It works.

---

ADXL345 glued with a glue gun to the bed temporarily for the test.

raw_data_z_adxl345_20250921_012012.zip (2.1 MB)

[dmbutyugin]

Thanks for testing, @nefelim4ag! This does look promising.

[mykepredko]

Sorry, what’s different about the “Old EI, graph/output” and “New EI, graph/output”?

They look identical and the graph source .csv filenames are the same.

[dmbutyugin]

I think ‘new’ refers to the new versions of EI* shapers from this PR (not merged just yet). Though this goes beyond the scope of this particular feature.

[mykepredko]

My expectation was that the “Old EI, graph/output” and “New EI, graph/output” were showing results before and after - the file name of the plot is the same, as is the data.

Shouldn’t the results be different after implementing the PR?

[nefelim4ag]

@mykepredko

Shouldn’t the results be different after implementing the PR?

resonance_tester produces and analyze the data.
The graph tool analyzes the data.

Shaper code changes how the analysis would be done.
(and how shapers would behave in printing.)

Graphs for EI, 2HUMP_EI, 3HUMP_EI shapers are different and the text output on the same data is different.

I’ve updated the New EI section, to add additional info, which would probably allows to avoid additional confusion later.

[dmbutyugin]

Input shaping is disabled during resonance testing. So the results should be the same regardless of whether input shaping is configured or not, or which version of it.

[MRX8024]

I find this innovation useful, as it significantly reduces z-axis vibration. Even if you don’t use zhop constantly (and many do, and it takes up significant print time), any z-axis movement will now be faster without increasing vibration. A resonance test for the z-axis can help identify and fix problems on this axis.

Vzbot235, attached the adxl345 to the bed base frame via screw. I have a standard base made of 2020 profile and plastic, as is the entire z-axis.

I increased these parameters because the vibrations were not noticeable against the background noise, but I overdid it a little, I think it’s not a big deal.

accel_per_hz_z: 40
sweeping_accel_z: 100

Without shaping

raw_data_z_20250921_132831.zip (2.9 MB)

With shaping

raw_data_z_20250921_133427.zip (2.5 MB)

With standard parameters and up to 200 Hz

raw_data_z_20250921_130933.zip (5.5 MB)

I think we have several resonances due to the transition nodes. The bed is driven by two trapezoidal screws through Oldham couplings, and then they are connected by a ring belt to a single motor.

Overall, I don’t think you even need to run a resonance test; the mere existence of the 3hump shaper at around 80Hz will dampen almost the entire range, and rounding is probably not important on z-axis. Do you have any comments on this, Dmitry?

If you need to test something else, let me know, I don’t plan to move away from this functionality, and the adxl will probably hang on the bed for a long time.

[dmbutyugin]

@MRX8024

I increased these parameters because the vibrations were not noticeable against the background noise, but I overdid it a little, I think it’s not a big deal.

Thanks, but I think these parameters are a bit too much for most of the printers. And I think the resonance test with default parameters already shows acceptable results (peaks of real resonances still go above the noise, and I think they are more or less the same as with your high parameters). I wonder if

TEST_RESONANCES AXIS=z ACCEL_PER_HZ=15 OUTPUT=raw_data

would already be good enough on your printer? Then I’d think that max_z_velocity=20 mm/sec and max_z_accel=1550 mm/sec^2 would still be acceptable for most printers, and thus accel_per_hz_z=15 could be set as a new default.

@MRX8024

Overall, I don’t think you even need to run a resonance test; the mere existence of the 3hump shaper at around 80Hz will dampen almost the entire range, and rounding is probably not important on z-axis. Do you have any comments on this, Dmitry?

This is true. I’d still recommend running the resonance test, especially now during the first testing phase to get a sense of where the resonances are. However, indeed something like 3hump_ei at around 80 Hz could be a reasonable all-round choice for most users, and could be recommended as a last resort, for instance.

[MRX8024]

Another vzbot235 from the community but with a metal z-axis. Default test settings.

Graph

raw_data_z_20250921_184858.zip (5.3 MB)

I would like to point out that the new method of resonance generation (sweeping) is very good for trapezoidal screws that have play in the nuts, and without it the measuremets is distorted. I’m not sure if it’s them exactly, but it’s likely.

Graph

raw_data_z_20250921_183906.zip (4.7 MB)

@dmbutyugin

I wonder if

TEST_RESONANCES AXIS=z ACCEL_PER_HZ=15 OUTPUT=raw_data

would already be good enough on your printer?

Graph

raw_data_z_20250921_223356.zip (2.6 MB)

I would say that this is still low, and I would like to see a clear 1e3, but as you can see the peaks are clearly visible, and in any case we will not be able to find the optimal value for all printers, I think that accel_per_hz_z=15 is a good default/starting point.

Issue:
If you turn off shaping for the z-axis via SET_INPUT_SHAPER, the report message does not label this axis.

Pic

I think the problem is somewhere here.

[dmbutyugin]

Thanks for sharing more data!

@MRX8024

I would like to point out that the new method of resonance generation (sweeping) is very good for trapezoidal screws that have play in the nuts, and without it the measuremets is distorted. I’m not sure if it’s them exactly, but it’s likely.

Yes, as I wrote in the beginning, previously I was concerned about how to tune input shaper for Z axis - you obviously cannot print a test, and the old test was no good for this application - it has too tiny amplitude of vibrations, effectively not being able to move the bed due to stiction and some backlash, and thus skewing the results for mid- and high frequencies.

@MRX8024

Issue:
If you turn off shaping for the z-axis via SET_INPUT_SHAPER, the report message does not label this axis.

I think the problem is somewhere here.

Well, as you can see from the code it is not a bug, but a feature. Once this is merged (hopefully), I did not want people to rush calibrating Z shaper just because the feature was added. The documentation will be updated, however, with all the necessary prefaces as to why and when you’d want to calibrate and enable it.

[MRX8024]

@dmbutyugin

Well, as you can see from the code it is not a bug, but a feature. Once this is merged (hopefully), I did not want people to rush calibrating Z shaper just because the feature was added. The documentation will be updated, however, with all the necessary prefaces as to why and when you’d want to calibrate and enable it.

If this functionality is already added to the main branch, the documentation will be updated. What’s the point of hiding the display of this axis in a command that people use primarily for calibration while reading this documentation? I admit that this news may be hype or something like that, but this is already the problem of people if they do not read the documentation. I consider this a bug, although not a critical one, but we could find another way to implement this check in the code if it is really needed. That’s just my opinion.

/

More graphs from another vzbot235, but this time with a mellow aluminium z-axis.

accel_per_hz_z=12.5

raw_data_z_20250923_112132.zip (5.2 MB)

accel_per_hz_z=15

raw_data_z_20250923_111551.zip (5.4 MB)

I also ran a test on my personal vz235 (from this post) with accel_per_hz_z=100, just for experiment.

accel_per_hz_z=100

raw_data_z_20250923_143816.zip (4.2 MB)

[dmbutyugin]

Thank you all! BTW, I’ve added a documentation to the branch. I think I’ll open the PR with this feature in the next few days.