Skip to content

README.md

Latest commit

 

History

History
573 lines (492 loc) · 24.8 KB

README.md

File metadata and controls

573 lines (492 loc) · 24.8 KB

More Math

Adds math nodes for numbers and types which do not need it. Inspired by the was_extras node.

WARNING This node is not compatible to ComfyUI-Impact-Pack and ComfyUI-Ovi which forces older antlr version via omegaconf

Quickstart

  1. Install ComfyUI.
  2. Clone this repository into ComfyUI/custom_nodes.
  3. open command prompt/terminal/bash in your comfy folder
  4. activate environment ./venv/Scripts/activate
  5. go to more_math folder cd ./custom_nodes/more_math/
  6. install requirements pip install -r requirements.txt
  7. Restart ComfyUI.

You can also get the node from comfy manager under the name of More math.

Features

  • Functions and variables in math expressions.
  • Conversion between INT and FLOAT, INT and BOOLEAN, and AUDIO and IMAGE
    • image/audio conversion encodes frequency content into RGB channels.
  • Node support for FLOAT, STRING, CONDITIONING, LATENT, IMAGE, MASK, NOISE, AUDIO, VIDEO, MODEL, CLIP, VAE, SIGMAS, and GUIDER.
  • Vector math with list literals [v1, v2, ...] and mixed operations between lists, scalars, and tensors.
  • Custom functions funcname(variable, variable, ...)->expression;
    • can be used later in expressions and in other custom functions,
    • shadowing built-in functions is not supported,
    • recursion is allowed, so be careful.
  • Custom variables varname=expression;
    • can be used later in the same expression chain,
    • compound assignments are supported: +=, -=, *=, /=, %=.
  • Indexed assignment a[i, j, ...] = expression;
    • supports multidimensional tensors and nested lists,
    • scalar values and 1-element tensors/lists fill the selected slice,
    • leading singleton dimensions are squeezed when needed to match target rank.
  • Control flow:
    • if/else
    • while
    • for
    • blocks { ... }
    • return
    • break
    • continue
  • Stack support shared across evaluations through stack connections.
    • useful for GuiderMath state between steps.
  • Comments:
    • line comments # ...
    • block comments /* ... */
  • When a tensor is expected, lists can often be used instead and will be promoted automatically.

Control Flow Statements

  • If/Else: if (condition) statement [else statement]
  • While Loops: while (condition) statement
  • Blocks: { statement1; statement2; ... }
    • New variables defined in blocks are isolated and don't leak to outer scope
    • Modifications to existing variables persist to outer scope
  • Return Statements: return [expression];
    • Early return from functions or top-level expressions
  • For Loops: for (variable in expression) statement
    • Iterates over list elements
    • Iterates over tensor elements along dimension 0
    • Scalars are treated as one-item iterables
  • Break/Continue: break;, continue;
    • Control loop execution (works in while and for loops)

Operators

  • Math: +, -, *, /, %, ^, |x| (abs / norm-style magnitude)
  • Assignment: =, +=, -=, *=, /=, =
  • Boolean: <, <=, >, >=, ==, != (false = 0.0, true = 1.0)
  • Bitwise shifts: <<, >>
  • Indexing: x[i] or x[i, j, ...]
    • works on tensors, nested lists, and strings,
    • supports scalar, tensor, and list indices.
  • Lists: [v1, v2, ...]
    • vector math is supported,
    • lists can broadcast across tensor operations in many cases,
    • lists can be used for color triples, coordinates, kernel sizes, and permutations.
  • Length Mismatch Handling: All math nodes (except Model, Clip, Vae which default to broadcast) include a length_mismatch option to handle inputs with different batch sizes, sample counts, or list lengths. The target length is determined by the maximum length among all provided inputs (a, b, c, d).
    • do nothing: dones no validation on input
    • tile: Repeats shorter inputs to match the maximum length.
    • error (Default): Raises a ValueError if any input lengths differ.
    • pad: Shorter inputs are padded with zeros to match the maximum length.

Functions

Functions are grouped by purpose.
The descriptions below reflect the runtime behavior implemented in UnifiedMathVisitor.py.

1) Core Math

1.1 Elementary & Numeric

  • abs(x) or |x|: absolute value; tensor/list inputs are handled element-wise.
  • sqrt(x): square root.
  • ln(x): natural logarithm.
  • log(x): base-10 logarithm.
  • exp(x): exponential e^x.
  • pow(x, y): power x^y.
  • floor(x): round down.
  • ceil(x): round up.
  • round(x): round to nearest integer.
  • fract(x): fractional part (x - floor(x)).
  • sign(x): sign (-1, 0, 1).
  • gamma(x): gamma function.
  • clamp(x, min, max): clamp to interval.
  • step(x, edge): returns 1 when x >= edge, otherwise 0.
  • dist(x1, y1, x2, y2) / distance: Euclidean distance between 2D points.

1.2 Trigonometric

  • sin(x): sine in radians.
  • cos(x): cosine in radians.
  • tan(x): tangent in radians.
  • asin(x): inverse sine.
  • acos(x): inverse cosine.
  • atan(x): inverse tangent.
  • atan2(y, x): quadrant-aware inverse tangent.

1.3 Hyperbolic

  • sinh(x): hyperbolic sine.
  • cosh(x): hyperbolic cosine.
  • tanh(x): hyperbolic tangent.
  • asinh(x): inverse hyperbolic sine.
  • acosh(x): inverse hyperbolic cosine.
  • atanh(x): inverse hyperbolic tangent.

1.4 Activation / ML

  • relu(x): max(0, x).
  • gelu(x): Gaussian Error Linear Unit.
  • softplus(x): smooth ReLU-like function.
  • sigm(x): sigmoid.
  • softmax(x, [dim]): softmax normalization.
  • softmin(x, [dim]): softmin normalization.
  • erf(x): error function.
  • erfinv(x): inverse error function.

1.5 Interpolation & Remap

  • lerp(a, b, t): linear interpolation.
  • smoothstep(x, e0, e1): 3rd-order smooth transition.
  • smootherstep(x, e0, e1): 5th-order smoother transition.
  • cubic_ease(a, b, t) / cubic: cubic easing interpolation.
  • sine_ease(a, b, t) / sine: sine easing interpolation.
  • elastic_ease(a, b, t) / elastic: elastic easing interpolation.
  • remap(v, i_min, i_max, o_min, o_max): map value from one interval to another.

2) Tensor, Stats & Data Ops

2.1 Element-wise / Tensor Math

  • tmin(x, y): element-wise minimum.
  • tmax(x, y): element-wise maximum.
  • tnorm(x): L2 normalization along the last dimension.
  • snorm(x): scalar/tensor norm magnitude.
  • cossim(a, b) / cosine_similarity: cosine similarity.
  • cov(x, y): covariance.
  • corr(x, y) / correlation: Pearson correlation.
  • entropy(x): Shannon entropy.
  • flip(x, dims): flip selected dimensions; dims can be a single dimension, list, or tensor of dimensions, so multiple axes can be flipped at once.
  • swap(tensor, dim, i1, i2): swap two indices along dimension dim.

2.2 Reductions & Statistical Aggregates

  • sum(x): sum.
  • mean(x): mean.
  • std(x): standard deviation.
  • var(x): variance.
  • median(x): median.
  • mode(x): mode.
  • quartile(x, k): quartile (k in 0..4).
  • percentile(x, p): percentile (p in 0..100).
  • quantile(x, q): quantile (q in 0..1).
  • moment(x, a, k): k-th moment around center a.
  • any(x): 1.0 if any element is non-zero.
  • all(x): 1.0 if all elements are non-zero.
  • count(x) / length(x) / cnt(x): number of elements or length.
  • cumsum(x): cumulative sum along dimension 0.
  • cumprod(x): cumulative product along dimension 0.
  • smin(x, ...): scalar minimum across inputs.
  • smax(x, ...): scalar maximum across inputs.

2.3 Sorting / Selection / Indices

  • sort(x): tensors are sorted along the last dimension (dim=-1); lists use Python sorting.
  • argsort(x, [descending]): returns indices along the last dimension, default descending=false.
  • argmin(x): global minimum index for tensors; list index for lists.
  • argmax(x): global maximum index for tensors; list index for lists.
  • topk(x, k): tensors keep the same shape and all non-top-k values are zeroed; lists return the sorted top-k slice.
  • botk(x, k): same as topk, but for smallest values.
  • topk_ind(x, k) / topk_indices: global top-k indices from flatten().
  • botk_ind(x, k) / botk_indices: global bottom-k indices from flatten().
  • unique(x): sorted unique values for tensors and lists.
  • where(cond, a, b): tensor broadcasting for tensor inputs; recursive truthy selection for lists/scalars.
  • histogram(x, bins, min, max) / hist: histogram counts from flatten() in the given interval.

2.4 Shape / Structure / Layout

  • shape(x): returns shape as a Python list.
  • flatten(x): flattens tensor or nested list.
  • reshape(tensor, shape) / rshp: reshape with element-count validation.
  • permute(tensor, dims) / perm: reorder dimensions.
  • crop(tensor, position, size): extract a region from tensor or string.
  • pad(tensor, padding): pad tensor.
  • overlay(base, overlay, offset, [opacity]): overlay one value/tensor onto another.
  • append(a, b): append or concatenate items, lists, and tensors.
  • batch_shuffle(tensor, indices) / shuffle / select: reorder along batch dimension.
  • concatenate(..., dim) / concat / cat: concatenate tensors or lists.
  • roll(tensor, shifts, [dim]): circular shift.
  • tensor(shape, [value, [type]]): create a filled tensor; type a tensor to copy its dtype to self when being created.

2.5 Linear Algebra

  • dot(a, b): dot product after flattening.
  • matmul(a, b): matrix multiplication.
  • cross(a, b): cross product; last dimension must be 3.
  • pinv(x): permutation inverse for permutation-like values.

2.6 Mapping / Sampling

  • map(tensor, c1, ...): coordinate remapping via grid_sample.
    • supports up to 3 coordinate inputs,
    • uses sampling coordinates derived from the provided coordinate tensors,
    • intended for spatial remapping / resampling.
  • get_value(tensor, position): read value at an N-D position using flat offset math.

3) Imaging & Spatial Processing

3.1 Filters & Convolution

  • blur(x, sigma) / gaussian: Gaussian blur using separable convolution.
  • edge(x, [kernel_size]): Sobel-style edge detection.
  • ezconvolution(tensor, ...) / ezconv: convolution with auto layout handling.
  • convolution(tensor, ...) / conv: direct convolution.

3.2 Mask Morphology

  • dilate(x, [kernel_size]): dilation.
  • erode(x, [kernel_size]): erosion.
  • morph_open(x, [kernel_size]): opening = erosion followed by dilation.
  • morph_close(x, [kernel_size]): closing = dilation followed by erosion.

4) Optical Flow

  • rife(img1, img2, [tiling_size, iterations, multi_scale]): compute optical flow.
  • motion_mask(flow): motion/occlusion mask from flow.
  • flow_to_image(flow): visualize flow as RGB.
  • flow_apply(image, flow): warp image by flow.
  • flow_mag(flow) / flow_magnitude: flow vector magnitude (or anything else, uses first 2 positions of last dimension).
  • flow_ang(flow) / flow_angle: flow vector angle in radians (atan2(dy, dx)). (or anything else, uses first 2 positions of last dimension)

5) Frequency Domain (FFT)

  • fft(x): fast Fourier transform across all dimensions.
  • ifft(x, [shape]): inverse FFT.
  • angle(x): phase angle of complex values.

6) Random & Noise

6.1 Random Distributions

  • All random generators are seeded and deterministic for a given seed.
  • All use the current node shape by default (based on shape of input to the node), but an optional shape argument can be provided to specify a different output shape.
  • all use rand<dist>(seed, [shape]) / random_<distribution> naming convention. noise/randn/random_normal is the same generator as in Random Noise node.
  • If shape is omitted, the current node shape is used.
  • noise / randn / random_normal: normal distribution.
  • rand / randu / random_uniform: uniform distribution.
  • rande / random_exponential: exponential distribution.
  • randc / random_cauchy: Cauchy distribution.
  • randln / random_log_normal: log-normal distribution.
  • randb / random_bernoulli: Bernoulli distribution.
  • randp / random_poisson: Poisson distribution.
  • randg / random_gamma: gamma distribution.
  • randbeta / random_beta: beta distribution.
  • randl / random_laplace: Laplace distribution.
  • randgumbel / random_gumbel: Gumbel distribution.
  • randw / random_weibull: Weibull distribution.
  • randchi2 / random_chi2: chi-squared distribution.
  • randt / random_studentt: Student’s t distribution.

6.2 Procedural Noise

  • perlin(seed, scale, [octaves, [offset, [shape]]]) / perlin_noise:
    • smooth gradient noise,
    • supports arbitrary dimensional grids.
  • voronoi(seed, scale, [jitter], [offset], [shape]) / cellular / worley / voronoi_noise / cellular_noise:
    • cellular / Voronoi noise,
    • jitter is clamped to 0..1.
  • plasma(seed, scale, [octaves, [offset, [shape]]]) / turbulence / plasma_noise:
    • high-frequency turbulence-style noise.

7) Bitwise

7.1 Shift Operators

  • a << b: Bitwise left shift.
  • a >> b: Bitwise right shift.

7.2 Bitwise Functions

  • band(a, b) / bitwise_and: bitwise AND.
  • bor(a, b) / bitwise_or: bitwise OR.
  • bxor(a, b) / bitwise_xor: bitwise XOR.
  • bnot(a) / bitwise_not: bitwise NOT.
  • bitcount(a) / popcount / popcnt: number of set bits.

8) Strings

  • upper(str): convert to uppercase.
  • lower(str): convert to lowercase.
  • trim(str): trim surrounding whitespace.
  • split(str, [delimiter]): split string.
  • join(list, [separator]): join list into string.
  • substring(str, start, [length]) / substr: substring extraction.
  • find(str, search): first match position.
  • replace(str, search, replacement): replace occurrences.

9) Color

  • rgb_to_hsv(...): convert RGB to HSV.
    • accepts packed tensor/list input or separate r, g, b,
    • optional fourth boolean argument enables hue in degrees.
  • hsv_to_rgb(...): convert HSV to RGB.
    • accepts packed tensor/list input or separate h, s, v,
    • optional fourth boolean argument treats hue as degrees.
  • int_to_rgb(value): convert packed integer color to RGB triplet.
  • rgb_to_int(...): convert RGB triplet to packed integer color.

10) Utility & Conversion

  • print(x): print value and return it.
  • print_shape(x) / pshp: print shape and return value.
  • range(start, end, step): numeric sequence as a list.
  • linspace(start, end, count): evenly spaced sequence.
  • logspace(start, end, count, base): logarithmically spaced sequence.
  • nan_to_num(x, nan, posinf, neginf) / nvl: replace NaN and infinities.
  • timestamp() / now: current Unix timestamp.
  • int(x): convert to int32 or nested int values.
  • float(x): convert to float or nested float values.

11) State / Stack

  • stack_push(id, value): push into stack slot.
  • stack_pop(id): pop from stack slot.
  • stack_get(id): read top value without removing it.
  • stack_clear(id): clear stack slot.
  • stack_has(id): check whether slot exists and is non-empty.

Variables

  • Common variables (except FLOAT, MODEL, VAE and CLIP):

    • D{N} - position in n-th dimension of tensor, for example D0, D1, D2
    • S{N} - size of n-th dimension of tensor, for example S0, S1, S2
    • V{N} - value input, for example V0, V1, V2
    • V - list of value inputs
    • F{N} - float input, for example F0, F1, F2
    • F - list of float inputs
    • Fcnt or F_count: number of float inputs
    • Vcnt or V_count: number of value inputs
    • depth: Current recursion depth (0 at top level)

  • common inputs (legacy):

    • a, b, c, d

  • Extra floats (legacy):

    • w, x, y, z

  • INSIDE IFFT

    • F or frequency_count – frequency count (freq domain, iFFT only)
    • K or frequency - isotropic frequency (Euclidean norm of indices, iFFT only)
    • Kx, Ky, K_dimN - frequency index for specific dimension
    • Fx, Fy, F_dimN - frequency count for specific dimension

  • IMAGE and LATENT:

    • C or channel - channel of image
    • X - X position in image, origin in top-left
    • Y - Y position in image, origin in top-left
    • W or width - image width
    • H or height - image height
    • B or batch - batch index
    • T or batch_count - number of batches
    • N or channel_count - channel count

  • IMAGE KERNEL:

    • kX, kY - position in kernel, centered at 0.0
    • kW, kernel_width - kernel width
    • kH, kernel_height - kernel height
    • kD, kernel_depth - kernel depth

  • AUDIO:

    • B or batch - batch index
    • N or channel_count - channel count
    • C or channel - audio channel
    • S or sample - current sample
    • T or sample_count - audio length in samples
    • R or sample_rate - sample rate

  • VIDEO

    • refer to IMAGE and LATENT for the visual part
    • batch means frame
    • batch_count means frame_count
    • refer to AUDIO for sound part

  • NOISE

    • refer to IMAGE and LATENT for most variables
    • I or input_latent - latent used as input to generate noise

  • GUIDER

    • refer to IMAGE and LATENT
    • sigma - current sigma value
    • seed - seed used for noise generation
    • steps - total number of sampling steps
    • current_step - current step index, 0..steps
    • sample - tensor input to guider or output from sampling

SelectiveGuiderMathNode (hooking)

Adds support for hooking into specific layers/blocks of the model during guided diffusion.

Current implementation details:

  • hook_target supports runtime filtering in node UI.
  • layer_x is used as direct index match (idx == layer_x) for current hook context.
  • For guiders with original_conds, base conditions are restored before reattaching hooks to avoid hook accumulation across reruns/interrupted runs.
  • Active hook paths currently include:
    • Attention override (attn1 / attn2 / double_block_attn / single_block_attn / attn_unknown)
    • DiT block replace (dit.double_block, dit.single_block)
    • UNet block patches (input_block_patch, middle_patch, output_block_patch)
    • Timestep embedding start via emb_patch (block_name="time_emb", layer_x=0)
    • Whole-model edges via diffusion-model wrapper (model_begin, model_end)

Side behavior (positive / negative)

When guider has original_conds, hooks are attached separately for:

  • positive
  • negative

Runtime variables expose side information:

  • cond_side: "positive" | "negative" | "mixed" | "unknown"
  • cond_index: 0 | 1 | -1
  • is_positive: 1.0 or 0.0
  • is_negative: 1.0 or 0.0

Variable reference (SelectiveGuiderMathNode)

The following variables are available in Expression.

Parser / grammar notes

The grammar in MathExpr.g4 accepts:

  • expressions, statements, blocks, function definitions, and variable assignments,
  • exprList for function arguments,
  • function groups by arity:
    • func0
    • func1
    • func2
    • func3
    • func4
    • func5
    • funcN
    • funcNoise
  • operator precedence:
    • unary
    • power
    • shift
    • multiply/divide/modulo
    • add/subtract
    • comparisons
    • ternary
  • literals:
    • NUMBER
    • STRING
    • CONSTANT (e, pi)
    • NONE
    • VARIABLE

Behavioral notes from the visitor

  • if, while, and for are statement-level constructs, not expression operators.
  • return may be used inside custom functions and top-level blocks.
  • break and continue are supported in loop bodies.
  • print_shape(x) prints a readable shape summary and returns the original value.
  • shape(x) returns a Python list, not a tensor.
  • range(...) returns a Python list of floats.
  • fft(x) and ifft(x) use the current tensor shape and expose frequency helper variables during ifft.
  • crop, overlay, pad, replace, split, join, substring, find, and trim also support string values where applicable.
  • rgb_to_hsv and hsv_to_rgb support both packed values and separate channel arguments.
  • tensor(shape, [value, [type]]) creates a tensor filled with value.
  • stack_* functions operate on persistent state shared across evaluations.

Practical examples

f(x)->x*x+1;
a=5;
f(a);

if (a > 0) { b = a * 2; } else { b = 0; }

topk([1, 9, 3, 7], 2)

rgb_to_hsv([1.0, 0.5, 0.25], true)

perlin(1234, 0.05, 4, [10, 20], [256, 256])
Variable Type Description
inp tensor Current tensor received by the active hook.
sample tensor Alias of inp.
F0..Fn float/tensor Individual float inputs from the node.
F list/tensor Collection of all float inputs.
D0..Dn tensor Per-dimension index tensors from generate_dim_variables.
S0..Sn float Per-dimension sizes from generate_dim_variables.
hook_kind string Active hook identifier: attn1, attn2, double_block_attn, single_block_attn, attn_unknown, dit_block, unet_block, model_begin, model_end, or unknown.
hook_domain string High-level domain: attention, diffusion, or unknown.
attn_kind string Attention kind: attn1, attn2, double_block_attn, single_block_attn, attn_unknown, or none outside attention hooks.
transformer_index float Attention sub-block index inside a UNet block (-1 if unavailable).
is_attn1 float (0/1) 1 when current hook is attn1, else 0.
is_attn2 float (0/1) 1 when current hook is attn2, else 0.
is_attn1_hook float (0/1) 1 when attn_kind=="attn1", else 0.
is_attn2_hook float (0/1) 1 when attn_kind=="attn2", else 0.
is_dit float (0/1) 1 when current hook is DiT block hook, else 0.
is_unet_block float (0/1) 1 when current hook is UNet block hook, else 0.
is_time_emb float (0/1) 1 when current hook is timestep embedding entry (block_name=="time_emb"), else 0.
block_name string Block/stage name (input, middle, output, time_emb, model, DiT block type, etc.).
layer_id float Numeric block/layer id used by current hook context.
layer float Alias of layer_id.
i float Alias of layer_id.
layer_key string Composite identifier for debug/filtering (for example output.6.attn2.0, unet.time_emb.0, model.begin).
total_blocks float Total blocks in stream if available, otherwise -1.
has_qkv float (0/1) 1 in attention hooks where q/k/v are valid; 0 in diffusion/block hooks.
q tensor Query tensor in attention hooks; fallback placeholder otherwise.
k tensor Key tensor in attention hooks; fallback placeholder otherwise.
v tensor Value tensor in attention hooks; fallback placeholder otherwise.
heads float Number of attention heads (attention hooks only, else 0).
dim_head float Per-head channel size (q.shape[-1] / heads) when available.
activations_shape list Raw shape from transformer context. Empty list if unavailable.
activation_b float Batch dimension from activations_shape[0] (or -1).
activation_c float Channel dimension from activations_shape[1] (or -1).
activation_h float Height dimension from activations_shape[2] (or -1).
activation_w float Width dimension from activations_shape[3] (or -1).
attn_mode string Legacy compatibility field (default unknown).
attention_relation string Inferred semantic relation: self, cross, or unknown.
is_self_attention float (0/1) 1 when the active attention is self-attention.
is_cross_attention float (0/1) 1 when the active attention is cross-attention.
has_context float (0/1) 1 when attention context appears to be present.
query_tokens float Query sequence length.
context_tokens float Context sequence length.
value_tokens float Value sequence length.
activation_rank float Rank of activations_shape.
activation_t float Temporal dimension for video-like activations (-1 if unavailable).

Practical notes

  • On SD1.x, repeated hits on the same layer_id are normal in attention because one UNet block can contain multiple transformer sub-blocks.

  • Use transformer_index to target exactly one sub-block.

  • For timestep-begin hooking use layer_x=0 and filter by block_name=="time_emb" (or layer_key=="unet.time_emb.0").

  • For model-edge hooks filter by hook_kind=="model_begin" or hook_kind=="model_end".

  • For model-agnostic expressions, prefer guard variables: has_qkv, is_dit, is_unet_block, is_attn1, is_attn2.

  • attn2 is only a hook label, not guaranteed to mean real cross-attention.

  • Use is_cross_attention only as an inferred relation from runtime metadata.

  • Use attention_relation for semantic relation (self/cross) and attn_kind for hook-path classification.

  • Selective guider math:

    • hook_target: all, dit_block, unet_block, attn1, attn2, double_block_attn, single_block_attn, model_begin, model_end