"""Support-preserving controls and explicit irreversible masked decoding. Research sampler is deliberately labeled separately from unmodified upstream. Random numbers are attached to complete global position arrays at each step. """ import math import numbers import torch def gate(strength, progress, gap, soft=True): if not soft: return ((strength > 0) & (progress <= strength)).to(strength.dtype) # Ramp ends at release threshold. g(0)=0 and limit alpha->0+ is 0 for p>=0. return ((strength-progress)/max(gap, 1e-6)).clamp(0, 1) * (strength > 0) def target_mask(shape, task, device='cuda'): mask = torch.zeros(shape, device=device, dtype=torch.float32) if len(shape) == 1: a,b=task.get('target_time',[.5,.8]); mask[int(a*shape[0]):max(int(b*shape[0]),int(a*shape[0])+1)]=1 elif len(shape) == 2: x0,y0,x1,y1=task.get('target_box',[.25,.25,.75,.75]) h,w=shape; mask[int(y0*h):max(int(y1*h),int(y0*h)+1),int(x0*w):max(int(x1*w),int(x0*w)+1)]=1 else: raise ValueError(f'Unsupported mask shape {shape}') return mask def categorical_position_sample(logits, generator): # Inverse CDF, one uniform draw per global position; no RNG draw per group. probs=logits.float().softmax(-1) uniforms=torch.rand(probs.shape[:-1],device=probs.device,generator=generator) sampled=(probs.cumsum(-1) upper if inclusive else value >= upper)): end = ']' if inclusive else ')' raise ValueError(f'{key} must be a finite number in [0, {upper}{end}') def _quota_commit(score, support, committed, wanted): """Reveal floor(T * wanted / N) target tokens cumulatively, when feasible. A proportional target quota is shared by balanced and control_aware. Clamp the next target increment to the available capacity of both regions; this also makes the final step reveal every remaining token. The reveal count and number of predictor calls are unchanged from the legacy cosine policy. """ current = int(committed.sum()) k = wanted - current newly = torch.zeros_like(committed) if not k: return newly target_done = int((committed & support).sum()) target_left = int((~committed & support).sum()) outside_left = int((~committed & ~support).sum()) desired = int(support.sum()) * wanted // support.numel() target_k = max(max(0, k - outside_left), min(min(k, target_left), desired - target_done)) for region, count in ((support, target_k), (~support, k - target_k)): if count: region_score = score.masked_fill(committed | ~region, -float('inf')) newly.scatter_(1, region_score.topk(count, dim=1).indices, True) return newly @torch.no_grad() def masked_decode(predict, reference, mask, mask_id, steps, job, trace): """predict(ids) -> [1,N,V]; defaults reproduce the legacy sampler. duration controls the reference release time. amplitude fixes the window over the full decode and varies its probability only. reference_copy=False still exposes reference tokens to the predictor, but never copies them into sampled candidates. control_aware is an experimental conflict penalty, not a validated authority estimator; it uses no additional predictor calls. Trace counts use flattened token positions. temporary/exposure/conflict are counted before the update; committed is cumulative after it; newly/direct copy refer only to this step's commits. A direct copy counts every committed position covered by the reference override, including coincident samples. """ _validate_masked_job(steps, job) ref=reference.reshape(1,-1).long(); support=mask.reshape(1,-1)>0 n=ref.shape[1]; device=ref.device if not n or support.shape != ref.shape: raise ValueError('reference and mask must have the same positive number of tokens') if mask.device != device or not bool(torch.isfinite(mask).all()) or bool(((mask < 0) | (mask > 1)).any()): raise ValueError('mask must be finite, in [0, 1], and on the reference device') if job['arm'] in ('guide', 'logit_bias') and not bool(support.any()): raise ValueError('guide and logit_bias require a nonempty target region') control_schedule = job.get('control_schedule', 'duration') reference_copy = job.get('reference_copy', True) control_mask = mask.reshape(1, -1) ids=torch.full_like(ref,mask_id) committed=torch.zeros_like(ids,dtype=torch.bool) generator=torch.Generator(device=device).manual_seed(job['seed']) reference_uniform=torch.rand(ref.shape,device=device,generator=torch.Generator(device=device).manual_seed(job.get('prior_seed',1234))) order_generator=torch.Generator(device=device).manual_seed(job['seed']+5678) random_priority=torch.rand(ref.shape,device=device,generator=order_generator) committed_at=torch.full_like(ids,-1) for step in range(steps): p=1-math.cos(step/steps*math.pi/2) reveal=1-math.cos((step+1)/steps*math.pi/2) delay=job.get('commitment_delay',0.) reveal=max(0.,(reveal-delay)/(1-delay)) if control_schedule == 'duration': g=gate(control_mask*job['alpha'],p,1/steps,job.get('soft_release',True)) else: # A fixed duration of one; alpha does not change the release time. g=gate(torch.ones_like(control_mask,dtype=torch.float32),p,1/steps,job.get('soft_release',True))*control_mask*job['alpha'] temporary=(reference_uniform=fraction),torch.full_like(ids,mask_id),visible) logits=predict(visible) if logits.ndim != 3 or logits.shape[:2] != ids.shape: raise ValueError(f'Expected [1,N,V], got {logits.shape}') if job['arm'] in ('guide','logit_bias'): # Discrete guide: logit correction, no arithmetic on token IDs. lead=torch.arange(n,device=device)[None,:]