Skip to main content

Crate hpdg

Crate hpdg 

Source
Expand description

§hpdg

hpdg is a Rust-first data generator for competitive programming and OI workflows. The crate takes inspiration from tools such as CYaRon, but it leans into Rust’s own strengths: strong typing, feature-gated modules, reproducible randomness, and composable building blocks.

§Why hpdg?

  • Build graph, string, vector, geometry, and query generators from a single crate.
  • Keep testcase generation reproducible with seeded RNG streams.
  • Use Rust-native abstractions such as traits and newtypes instead of stringly APIs.
  • Mix quick scripts and larger generator codebases without changing tools.

§Quick Start

use hpdg::graph::Graph;
use hpdg::io::IO;
use hpdg::string::{SentenceConfig, StringGen};
use hpdg::vector::{IntRange, Vector};

let mut io = IO::new("sample".to_string());

let mut graph = Graph::new(4, false);
graph.add_edge(1, 2, None);
graph.add_edge(2, 3, None);

let points = Vector::random_int(2, &[IntRange::MinMax(1, 5), IntRange::MinMax(10, 20)]);

let mut cfg = SentenceConfig::default();
cfg.sentence_terminators = ".".to_string();
let sentence = StringGen::random_sentence(4, Some(&cfg));

io.input_writeln("4 2");
io.input_writeln(graph);
io.input_writeln(points.len());
io.input_writeln(sentence);

§Module Guide

  • io: testcase buffers, file naming, process execution, and streaming output.
  • graph: graph containers plus random trees, DAGs, connected graphs, and helpers.
  • math: number theory, combinatorics, digit helpers, and formatting utilities.
  • sequence: memoized formula-based sequences and common progressions.
  • vector: random integer and floating-point vectors and matrices.
  • string: random words, sentences, paragraphs, dictionary sampling, and regex-like text.
  • polygon: integer geometry helpers, convex hulls, and simple polygons.
  • query: random range queries, mixed update/query streams, and weighted generators.
  • compare: compare outputs from strings, files, or child processes with custom graders.
  • rng: deterministic RNG wrappers and reproducible stream splitting.
  • core and traits: Rust-flavored primitives such as newtypes and generator traits.

§Common Workflows

§Feature Guide

Most modules are enabled by default. The most relevant optional integration features are:

  • python-bindings: enables PyO3-based Python bindings.
  • c-bindings: enables the experimental C ABI module.

Internal feature flags such as graph, io, math, query, string, and vector mostly mirror module boundaries and can be used to slim down builds.

§Examples Index

  • examples/full_generation.rs: end-to-end sample combining graph, vector, string, and I/O.
  • docs/rust-quickstart.md: short Rust-oriented getting-started notes.
  • docs/cyaron-api.md: rough API mapping from CYaRon concepts to hpdg.
  • Want deterministic testcase families? Start with rng.
  • Want local judge-like verification? Jump to compare.
  • Want graph generators specifically? graph::Graph is the main entry point.
  • Want ergonomic file naming and flushing? See io::IO and testcase::Testcase.

If you are new to the crate, the smoothest way to explore it is:

  1. Start with io::IO for testcase structure and file output.
  2. Pick a generator module such as graph::Graph, string::StringGen, or vector::Vector.
  3. Use rng::SeededRng or rng::RngStream when you need reproducible cases.
  4. Add compare helpers when you want a local standard-solution workflow.

§Stability

hpdg is still evolving. The core modules are usable today, but APIs may change before 1.0 as the crate becomes more polished and more Rust-idiomatic.

Modules§

compare
Output comparison utilities and customizable graders. Output-comparison utilities for local judging workflows.
core
Rust-first primitives such as strongly typed node and edge identifiers. Core Rust-first building blocks shared across the crate.
error
Shared error types used across the crate. Shared error types for fallible hpdg workflows.
graph
Graph containers, formatters, and random graph/tree generators. Graph containers and random graph generators.
io
Testcase I/O buffers, file naming, process execution, and streaming writers. Testcase I/O buffers, file naming, process execution, and streaming output.
math
Math helpers for number theory, combinatorics, digits, and formatting. Math helpers for number theory, combinatorics, digit tricks, and formatting.
polygon
Integer geometry helpers for points and polygons. Integer geometry helpers for competitive-programming testcases.
query
Random range-query generators, including weighted and mixed workloads. Random range-query generators.
rng
Deterministic RNG wrappers and reproducible random streams. Deterministic and platform-friendly random helpers.
sequence
Memoized formula-based sequences and common progression helpers. Formula-driven and memoized sequences.
string
Random strings, words, sentences, paragraphs, and regex-like generators. Random string and text generators.
testcase
Backward-compatible alias around io::IO. Backward-compatible testcase alias.
traits
Traits for building reusable generator abstractions. Traits for building reusable generators on top of hpdg.
utils
Small utility helpers for argument parsing, path escaping, and trait probes. Small utility helpers used by generators and command-line entrypoints.
vector
Random vectors, matrices, and vector formatting utilities. Random vector and matrix helpers.