<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\tests;
use seekquarry\yioop\library\av_processing\CeltBands;
use seekquarry\yioop\library\av_processing\CeltShape;
use seekquarry\yioop\library\av_processing\CeltBandReader;
use seekquarry\yioop\library\av_processing\Pvq;
use seekquarry\yioop\library\av_processing\RangeDecoder;
use seekquarry\yioop\configs as C;
use seekquarry\yioop\library\UnitTest;
/**
* Checks the steps that turn a band's stored pattern of pulses into
* the tones the band holds.
*
* The main one is the smearing. A pattern of pulses leaves most slots
* empty, and played as it stands the silence between the pulses is
* heard as a ringing, so the pattern is smeared across the band by
* turning neighboring slots slightly into each other. Two things have
* to hold for that to be right. It must leave the band's loudness
* exactly where it was, since it is meant to change the shape and
* nothing else. And it must be undoable, since a turning that lost
* information would not be a turning at all. Both are checked here,
* and either failing would mean the smearing is doing something other
* than what it claims.
*
* The two approximations are checked against the true functions they
* approximate. They exist because their answers feed back into how the
* room is shared out, so they have to come out identical on every
* machine, which an ordinary cosine cannot promise.
*
* @author Chris Pollett
*/
class CeltShapeTest extends UnitTest
{
/**
* How close the approximations have to come to the true functions
*/
const CLOSE_ENOUGH = 1e-3;
/**
* How close a turning has to come to giving back what it was given
*/
const VERY_CLOSE = 1e-8;
/**
* A whole, against which the cosine counts
*/
const WHOLE = 32768;
/**
* A quarter turn, in the units the cosine takes
*/
const QUARTER_TURN = 16384;
/**
* The smearing setting the recordings mostly use
*/
const USUAL_SMEAR = 2;
/**
* A starting point for the made up numbers
*/
const SEED = 20260803;
/**
* Brings in the writer used to make a band to read back
*/
public function setUp()
{
if (!class_exists("seekquarry\\yioop\\tests\\RangeEncoder")) {
require_once C\PARENT_DIR . "/tests/test_files/RangeEncoder.php";
}
mt_srand(self::SEED);
}
/**
* Nothing needs clearing away after these cases
*/
public function tearDown()
{
}
/**
* Makes up a band's slots to work on
*
* @param int $length how many slots
* @return array the slots
*/
public function madeUpBand($length)
{
$band = [];
for ($i = 0; $i < $length; $i++) {
$band[] = mt_rand(-1000, 1000) / 1000.0;
}
return $band;
}
/**
* How loud a band is, taken as the sum of its slots squared
*
* @param array $band the band's slots
* @return float how loud it is
*/
public function loudnessOf($band)
{
$total = 0.0;
foreach ($band as $slot) {
$total += $slot * $slot;
}
return $total;
}
/**
* Smearing changes the shape of a band and must leave its loudness
* exactly where it was
*/
public function smearingLeavesLoudnessAloneTestCase()
{
$worst = 0.0;
$changed = 0.0;
foreach ([16, 32, 64] as $length) {
foreach ([1, 2, 3] as $setting) {
$band = $this->madeUpBand($length);
$before = $this->loudnessOf($band);
$smeared = $band;
CeltShape::smear($smeared, $length, -1, 1, 3, $setting);
$worst = max($worst,
abs($this->loudnessOf($smeared) - $before) / $before);
for ($i = 0; $i < $length; $i++) {
$changed = max($changed, abs($smeared[$i] - $band[$i]));
}
}
}
$this->assertTrue($worst < self::VERY_CLOSE,
"smearing leaves the band's loudness where it was");
$this->assertTrue($changed > 0.01,
"smearing does change the band's shape");
}
/**
* Smearing must be undoable, since a turning that lost anything
* would not be a turning
*/
public function smearingCanBeUndoneTestCase()
{
$worst = 0.0;
foreach ([16, 48] as $length) {
foreach ([1, 2, 3] as $setting) {
foreach ([1, 2] as $groups) {
$band = $this->madeUpBand($length);
$there = $band;
CeltShape::smear($there, $length, -1, $groups, 3,
$setting);
CeltShape::smear($there, $length, 1, $groups, 3,
$setting);
for ($i = 0; $i < $length; $i++) {
$worst = max($worst, abs($there[$i] - $band[$i]));
}
}
}
}
$this->assertTrue($worst < self::VERY_CLOSE,
"smearing and undoing gives back what was started with");
}
/**
* A band with a pulse in half its slots has no gaps worth filling,
* and one setting says to leave the band alone, so neither is
* smeared
*/
public function someBandsAreLeftAloneTestCase()
{
$length = 16;
$band = $this->madeUpBand($length);
$plenty = $band;
CeltShape::smear($plenty, $length, -1, 1, $length, self::USUAL_SMEAR);
$this->assertEqual($plenty, $band,
"a band with pulses in half its slots is left alone");
$told = $band;
CeltShape::smear($told, $length, -1, 1, 3, CeltShape::NO_SMEAR);
$this->assertEqual($told, $band,
"the setting that says to leave a band alone does so");
}
/**
* A band with few pulses has more gaps and should be smeared
* harder than one with many.
*
* This is checked where the band is looked at in enough groups
* that only neighboring slots are turned into each other. A band
* long enough for the second, wider turning behaves differently,
* because that turning takes the same two numbers the other way
* round and so grows as the first shrinks. Both are wanted; only
* the first is a simple trend.
*/
public function fewerPulsesAreSmearedHarderTestCase()
{
$length = 16;
$groups = 4;
$band = $this->madeUpBand($length);
$before = 0.0;
$falling = true;
foreach ([1, 2, 3, 5, 7] as $pulses) {
$smeared = $band;
CeltShape::smear($smeared, $length, -1, $groups, $pulses,
self::USUAL_SMEAR);
$moved = 0.0;
for ($i = 0; $i < $length; $i++) {
$moved += abs($smeared[$i] - $band[$i]);
}
if ($before > 0.0 && $moved >= $before) {
$falling = false;
}
$before = $moved;
}
$this->assertTrue($falling,
"each extra pulse leaves the band nearer where it started");
$this->assertTrue($before > 0.0,
"a band with pulses to spare is still smeared a little");
}
/**
* Pairing up the slots of a band is its own opposite, so doing it
* twice gives back what was started with, and it leaves the band's
* loudness alone
*/
public function pairingUpIsItsOwnOppositeTestCase()
{
$length = 32;
$band = $this->madeUpBand($length);
$before = $this->loudnessOf($band);
$paired = $band;
CeltShape::pairUp($paired, 0, $length, 1);
$this->assertTrue(abs($this->loudnessOf($paired) - $before) /
$before < self::CLOSE_ENOUGH,
"pairing up leaves the band's loudness where it was");
CeltShape::pairUp($paired, 0, $length, 1);
$worst = 0.0;
for ($i = 0; $i < $length; $i++) {
$worst = max($worst, abs($paired[$i] - $band[$i]));
}
$this->assertTrue($worst < self::CLOSE_ENOUGH,
"pairing up twice gives back what was started with");
}
/**
* The cosine that comes out the same on every machine should
* follow the true cosine across the range it is used over
*/
public function steadyCosineFollowsTheTrueOneTestCase()
{
$worst = 0.0;
for ($turn = 0; $turn < self::QUARTER_TURN; $turn += 59) {
$mine = CeltShape::steadyCos($turn) / self::WHOLE;
$true_value = cos(0.5 * M_PI * $turn / self::QUARTER_TURN);
$worst = max($worst, abs($mine - $true_value));
}
$this->assertTrue($worst < self::CLOSE_ENOUGH,
"the steady cosine follows the true one throughout");
$this->assertEqual(CeltShape::steadyCos(0), self::WHOLE,
"at no turn at all it gives the whole");
$this->assertTrue(CeltShape::steadyCos(self::QUARTER_TURN - 1) < 10,
"at nearly a quarter turn it gives nearly nothing");
}
/**
* The logarithm of how far a split leaned should follow the true
* logarithm of the same ratio
*/
public function leanLogarithmFollowsTheTrueOneTestCase()
{
$worst = 0.0;
$tried = 0;
for ($turn = 1000; $turn < 15000; $turn += 311) {
$up = CeltShape::steadyCos(self::QUARTER_TURN - $turn);
$across = CeltShape::steadyCos($turn);
$mine = CeltShape::leanLog($up, $across) / 2048.0;
$worst = max($worst, abs($mine - log($up / $across, 2)));
$tried++;
}
$this->assertTrue($tried > 40, "many leans were tried");
$this->assertTrue($worst < 0.05,
"the lean logarithm follows the true one throughout");
$this->assertEqual(CeltShape::leanLog(1000, 1000), 0,
"a split that leaned neither way gives nothing");
}
/**
* Every lean a split band can report should be read back as the
* value that was written.
*
* A lean says how a band's loudness divided between its two halves,
* and a stretch that did not change suddenly stores it with the
* middle more likely than the ends, since an even split is the
* common case. Reading it back wrongly would put a band's energy in
* the wrong half while consuming exactly the right number of bits,
* so nothing downstream would notice. Every value at every size up
* to a hundred and twenty eight steps is checked here rather than a
* sample; widening the list of sizes sweeps further at the cost of
* a slower case.
*/
public function everyLeanIsReadBackTestCase()
{
$wrong = 0;
$tried = 0;
foreach ([2, 4, 8, 16, 32, 64, 128] as $steps) {
for ($turn = 0; $turn <= $steps; $turn++) {
$writer = new RangeEncoder(400);
$this->writeLean($writer, $turn, $steps);
$reader = new LeanReader(new RangeDecoder($writer->finish()));
if ($reader->readTriangular($steps) != $turn) {
$wrong++;
}
$tried++;
}
}
$this->assertTrue($tried > 250, "every lean at every size tried");
$this->assertEqual($wrong, 0,
"every lean reads back as it was written, $tried tried");
}
/**
* Writes a lean the way the specification stores it, so that what
* the reader gives back can be checked against it
*
* @param object $writer the writer partway through a piece
* @param int $turn which step the lean fell on
* @param int $steps how many steps the lean is stored in
*/
public function writeLean($writer, $turn, $steps)
{
$half = $steps >> 1;
$whole = ($half + 1) * ($half + 1);
if ($turn <= $half) {
$width = $turn + 1;
$below = ($turn * ($turn + 1)) >> 1;
} else {
$width = $steps + 1 - $turn;
$below = $whole -
((($steps + 1 - $turn) * ($steps + 2 - $turn)) >> 1);
}
$writer->encode($below, $below + $width, $whole);
}
/**
* A band read out of a stretch should come back at the loudness
* asked for
*/
public function bandComesBackAtTheLoudnessAskedForTestCase()
{
$length = 16;
$pulses = 5;
$wanted = 2.5;
$writer = new RangeEncoder(200);
$writer->encodeNumber(11, Pvq::patternCount($length, $pulses));
$reader = new RangeDecoder($writer->finish());
$read = CeltShape::readBand($reader, $length, $pulses,
self::USUAL_SMEAR, 1, $wanted);
$loudness = sqrt($this->loudnessOf($read["shape"]));
$this->assertTrue(abs($loudness - $wanted) < self::CLOSE_ENOUGH,
"the band comes back at the loudness asked for");
$this->assertEqual(count($read["shape"]), $length,
"the band has as many slots as it should");
}
/**
* A group of a band left with no pulses should be reported as
* empty, since a later step fills those back in rather than
* letting them ring
*/
public function emptyGroupsAreFoundTestCase()
{
$pattern = [2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0];
$this->assertEqual(CeltShape::filledGroups($pattern, 16, 2), 3,
"both halves hold something");
$pattern = [2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
$this->assertEqual(CeltShape::filledGroups($pattern, 16, 2), 1,
"only the first half holds anything");
$pattern = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0];
$this->assertEqual(CeltShape::filledGroups($pattern, 16, 2), 2,
"only the second half holds anything");
$this->assertEqual(CeltShape::filledGroups($pattern, 16, 1), 1,
"a band looked at in one group is never called empty");
}
/**
* Putting a band's shape back together with its loudness should
* scale the band and leave the ones around it alone
*/
public function loudnessIsAppliedToTheShapeTestCase()
{
$doublings = 3;
$edges = CeltBands::edgesFor($doublings);
$length = $edges[CeltBands::BAND_COUNT];
$shape = array_fill(0, $length, 0.5);
$loudness = array_fill(0, CeltBands::BAND_COUNT, 0.0);
$loudness[3] = 2.0;
$tones = CeltShape::toTones($shape, $loudness, $doublings, 0,
CeltBands::BAND_COUNT, $length);
$quiet = $tones[$edges[3]];
$loudness[3] = 4.0;
$louder = CeltShape::toTones($shape, $loudness, $doublings, 0,
CeltBands::BAND_COUNT, $length);
$loud = $louder[$edges[3]];
/* Each whole step doubles the scale, so two steps make a band
four times as loud. The comparison is between the same band
at two loudnesses, since different bands start from
different expectations. */
$this->assertTrue($loud > $quiet * 3.99 && $loud < $quiet * 4.01,
"two whole steps of loudness makes a band four times as loud");
$this->assertTrue($quiet > 0.0, "the quieter band is still there");
}
}
/**
* Lets a lean be read on its own, without a whole stretch around it.
*
* The lean reader lives inside the class that walks a band's splits and
* needs a good deal of state around it. This stands that state down to
* the one thing a lean actually needs, which is somewhere to read from.
*/
class LeanReader extends CeltBandReader
{
/**
* Sets up a reader over one written lean
*
* @param object $reader a reader over the piece holding the lean
*/
public function __construct($reader)
{
$this->reader = $reader;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software