YUL-PHASER(1)

📦
version 0.8.38 · 4 versions
, in fedora 43, fedora 44

💅 yul-phaser — the manual, but make it cute

okay so bestie, this is the manual page for yul-phaser, a User Commands situation, and honestly? it's giving mad scientist but in a good way. it's version 0.8.38 (yes that's the same number as the NAME line, i checked, it's fine, that's just how manpages work 💖).

✨ NAME ✨

yul-phaser — manual page for yul-phaser 0.8.38. that's it. that's the name. short, sweet, iconic. 👑

🌸 SYNOPSIS 🌸

yul-phaser [options] <file>

🦋 DESCRIPTION 🦋

so yul-phaser is a tool for finding the best sequence of Yul optimisation phases. that's the whole vibe.

it reads <file> as Yul code and then tries to find the best order in which to run optimisation phases, using a genetic algorithm. like, it's literally doing evolution but for compiler passes. Darwin could never. 🧬

example, because examples are everything:

yul-phaser program.yul

and here come the allowed options, buckle up buttercup, there's a LOT:

💅 OPTIONS 💅

🔧 GENERAL:

  • --help — show the help message and dip out. bye! 👋
  • --input-files <PATH> — the input files. yes. that's it. straightforward fr.
  • --prefix <CHROMOSOME> — initial optimisation steps that get automatically applied to every input program, no exceptions. the result is treated as if it was the actual input, i.e. these steps are not considered a part of the chromosomes and cannot be mutated. also, the values of relative metric values are relative to the fitness of a program with these steps applied, rather than the fitness of the original program. heads up: phaser always adds a 'hgo' prefix to make sure chromosomes can contain arbitrary optimisation steps — this implicit prefix cannot be changed or or removed using this option. the value you give here is applied after it. 🫶
  • --seed <NUM> — seed for the random number generator. for when you want your chaos to be reproducible. 💫
  • --rounds <NUM> — the number of rounds after which the algorithm should stop (default=no limit). infinite slay, apparently.
  • --mode <NAME> (=run-algorithm) — mode of operation. the default is to run the algorithm, but you can also tell phaser to do something else with its parameters, e.g. just print the optimised programs and exit.

AVAILABLE MODES:

  • run-algorithm
  • print-optimised-programs
  • print-optimised-asts

🧬 ALGORITHM:

  • --algorithm <NAME> (=GEWEP) — the algorithm. pick your fighter.

AVAILABLE ALGORITHMS:

  • GEWEP
  • classic
  • random
  • --no-randomise-duplicates — by default, after each round of the algorithm, duplicate chromosomes are removed from the population and replaced with randomly generated ones. this option disables that postprocessing. no fresh blood for you. 🙈
  • --min-chromosome-length <NUM> (=100) — minimum length of randomly generated chromosomes.
  • --max-chromosome-length <NUM> (=100) — maximum length of randomly generated chromosomes.
  • --crossover <NAME> (=uniform) — the type of crossover operator to use. very matchmaker of you.

AVAILABLE CROSSOVER OPERATORS:

  • single-point
  • two-point
  • uniform
  • --uniform-crossover-swap-chance <PROBABILITY> (=0.5) — the chance of two genes being swapped between chromosomes in uniform crossover. 🎲

🔥 GEWEP ALGORITHM:

  • --gewep-mutation-pool-size <FRACTION> (=0.25) — percentage of population to regenerate using mutations in each round.
  • --gewep-crossover-pool-size <FRACTION> (=0.25) — percentage of population to regenerate using crossover in each round.
  • --gewep-randomisation-chance <PROBABILITY> (=0.90000000000000002) — the chance of choosing gene randomisation as the mutation to perform. (yes, that many digits. they said what they said. 💀)
  • --gewep-deletion-vs-addition-chance <PROBABILITY> (=0.5) — the chance of choosing gene deletion as the mutation if randomisation was not chosen.
  • --gewep-genes-to-randomise <PROBABILITY> — the chance of any given gene being mutated in gene randomisation. (default=1/max-chromosome-length)
  • --gewep-genes-to-add-or-delete <PROBABILITY> — the chance of a gene being added (or deleted) in gene addition (or deletion). (default=1/max-chromosome-length )

👑 CLASSIC GENETIC ALGORITHM:

  • --classic-elite-pool-size <FRACTION> (=0.25) — percentage of population to regenerate using mutations in each round.
  • --classic-crossover-chance <FRACTION> (=0.75) — chance of a chromosome being selected for crossover.
  • --classic-mutation-chance <FRACTION> (=0.01) — chance of a gene being mutated.
  • --classic-deletion-chance <PROBABILITY> (=0.01) — chance of a gene being deleted.
  • --classic-addition-chance <PROBABILITY> (=0.01) — chance of a random gene being added.

🎲 RANDOM ALGORITHM:

  • --random-elite-pool-size <FRACTION> — percentage of the population preserved in each round. (default=one individual, regardless of population size)

🌈 POPULATION:

  • --population <CHROMOSOMES> — list of chromosomes to be included in the initial population. you can specify multiple values separated with spaces, or invoke the option multiple times, and all the values will be included. flexible queen behavior. ✨
  • --random-population <SIZE> — the number of randomly generated chromosomes to be included in the initial population.
  • --population-from-file <FILE> — a text file with a list of chromosomes (one per line) to be included in the initial population.
  • --population-autosave <FILE> — if specified, the population is saved in the specified file after each round. (default=autosave disabled)

📏 METRICS:

  • --metric <NAME> (=relative-code-size) — metric used to evaluate the fitness of a chromosome. it's like a vibe check but for code. ⭐

AVAILABLE METRICS:

  • code-size
  • relative-code-size
  • --metric-aggregator <NAME> (=average) — operator used to combine multiple fitness metric values obtained by evaluating a chromosome separately for each input program.

AVAILABLE METRIC AGGREGATORS:

  • average
  • sum
  • maximum
  • minimum
  • --relative-metric-scale <EXPONENT> (=3) — scaling factor for values produced by relative fitness metrics. since all metrics must produce integer values, the fractional part of the result is discarded. to keep the numbers meaningful, a relative metric multiplies its values by a scaling factor, and this option specifies the exponent of this factor. for example, with a value of 3 the factor is 10^3 = 1000 and the metric will return 500 to represent 0.5, 1000 for 1.0, 2000 for 2.0, and so on. using a bigger factor allows discerning smaller relative differences between chromosomes, but it makes the numbers less readable and may also lose precision if the numbers are very large. 🧮
  • --chromosome-repetitions <COUNT> (=1) — number of times to repeat the sequence optimisation steps represented by a chromosome.

⚖️ METRIC WEIGHTS:

  • --expression-statement-cost <COST> (=1)
  • --assignment-cost <COST> (=1)
  • --variable-declaration-cost <COST> (=1)
  • --function-definition-cost <COST> (=1)
  • --if-cost <COST> (=2)
  • --switch-cost <COST> (=1)
  • --case-cost <COST> (=2)
  • --for-loop-cost <COST> (=3)
  • --break-cost <COST> (=2)
  • --continue-cost <COST> (=2)
  • --leave-cost <COST> (=2)
  • --block-cost <COST> (=1)
  • --function-call-cost <COST> (=1)
  • --identifier-cost <COST> (=1)
  • --literal-cost <COST> (=1)

💾 CACHE:

  • --program-cache — enables caching of intermediate programs corresponding to chromosome prefixes. this speeds up fitness evaluation by a lot, but it eats tons of memory if the chromosomes are long. disabled by default, since there's currently no way to set an upper limit on memory usage — but highly recommended if your computer has enough RAM. treat your RAM like a snack, bestie. 🍓

🖨️ OUTPUT:

  • --show-initial-population — print the state of the population before the algorithm starts.
  • --show-only-top-chromosome — print only the best chromosome found in each round rather than the whole population. main character only. 👑
  • --hide-round — hide information about the current round (round number and elapsed time).
  • --show-cache-stats — print information about cache size and effectiveness after each round.
  • --show-seed — print the selected random seed. 🎀
ok and that's the whole page, you read all of it, i'm so proud of you bestie 🫶

and finally, the cute lil sign-off: this little masterpiece is yul-phaser 0.8.38, dated October 2026, filed under YUL-PHASER(1) in the User Commands section. iykyk. now go optimise something. 💜✨

📦 where this page comes from