Random generators

PiMath.Random builds a new object at each call, from a configuration object. Every option is optional.

// degree 2, integer coefficients
PiMath.Random.polynom()
PiMath.Random.polynom({degree: 3, variables: 'x'})

Available generators

Generator	Returns	Typical use
Random.fraction(config)	Fraction	A coefficient
Random.monom(config)	Monom	A term
Random.polynom(config)	Polynom	An expression, possibly factorable
Random.equation(config)	Equation	An equation with controlled solutions
Random.point(config), Random.point3(config)	Point	A point in the plane or in space
Random.vector(config), Random.vector3(config)	Vector	A vector
Random.line(config), Random.line3(config)	Line, Line3	A line
Random.circle(config)	Circle	A circle

Small helpers are also available: number, numberSym, prime, triplet, bool, array, item, shuffle.

Shared conventions

• Coefficients. fraction: false (default) gives integers, fraction: true gives fractions, and an object gives full control (max, reduced, range, ...).
• Allowed values. Permissions are grouped in allow: allow.zero, allow.negative, allow.positive... Zero is not allowed by default.
• Integers. An integer of either sign is called relative (fraction: {relative: true}).
• Ranges. range: 5 means [-5, 5], and range: {min: -2, max: 8} gives explicit bounds.
• Probabilities. An option that selects a kind of result (a type of line, an equation without solution...) accepts true, false or a probability between 0 and 1.
• Validation. A wrong configuration throws an InvalidArgumentError at every call, never depending on chance. See errors.

Random.polynom({degree: -1}) // throws InvalidArgumentError
Random.point({axis: 'x', range: {min: 1, max: 3}}) // throws InvalidArgumentError

Numbers

Random.fraction().isZero() // false
Random.fraction({relative: true}).isRelative() // true
Random.fraction({allow: {negative: false}}).isStrictlyPositive() // true
Math.abs(Random.fraction({range: 3}).value) <= 3 // true

fraction is the model of every coefficient option. A fraction option elsewhere takes the same keys. The complete list is below.

Algebra

Monoms and polynomials

Random.monom({degree: 2, variables: 'x'}).degree().display // 2
Random.polynom({degree: 3}).degree().display // 3
Random.polynom({degree: 2, variables: 't'}).variables // [ 't' ]
Random.polynom({degree: 4, numberOfMonoms: 2}).length <= 2 // true
Random.polynom({degree: 2, allow: {negativeLeading: false}}).monomByDegree().coefficient.isPositive() // true

With factorable: true the polynomial is a product of linear factors, so its roots are known. allow.commonFactor: false removes any common integer factor.

Random.polynom({degree: 2, factorable: true}).roots.length > 0 // true

Equations

The solution option controls the roots, which is what an exercise needs.

const e = Random.equation({
    degree: 2,
    solution: {count: 2, relative: true, range: 6}
})

e.tex // e.g. x^{ 2 }+3x-4=0
e.solve().map(s => s.tex) // e.g. [ '-4', '1' ]
e.solve().length // 2

Random.equation({degree: 3, solution: {count: 1}}).solve().length // 1
Random.equation({degree: 2, solution: {count: 2, allowZero: false}}).solve().some(s => s.isZero()) // false

solution.nothing and solution.everything build an equation with no solution (P + k = P) or with infinitely many (P = P). shuffle: true adds the same random polynomial to both sides, so the equation does not start with a zero right member.

Geometry in the plane

Points and vectors

axis forces a coordinate to zero, quadrant fixes signs. They are independent: quadrant: 1 includes the axes, so combine it with axis: false to stay strictly inside.

Random.point({quadrant: 1}).tex // e.g. \left(8;5\right)
Random.point({quadrant: 3}).x.isStrictlyPositive() // false
Random.point({axis: 'x'}).y.isZero() // true
Random.point({axis: false, quadrant: 2}).x.isStrictlyNegative() // true
Math.abs(Random.point({range: 2}).x.value) <= 2 // true
Random.point({fraction: true}).dimension // 2

A vector is drawn like a point, with the same options. The zero vector is excluded unless allow.zero is true, and primitive: true gives integer components without common divisor.

Random.vector().isZero() // false
Random.vector({axis: 'y'}).x.isZero() // true
Random.vector({primitive: true}).dimension // 2

Lines

A line comes from a point A and a slope. A is a Point or a point configuration, and slope is an exact value or {fraction}.

Random.line({slope: 2}).slope.display // 2
Random.line({A: new Point(1, 2)}).isPointOnLine(new Point(1, 2)) // true

allow chooses the kind of line: vertical, horizontal, positive and negative (the sign of the slope). Each one is false, a probability, or true (default).

Random.line({allow: {vertical: 1}}).isVertical() // true
Random.line({allow: {vertical: false, horizontal: 1}}).isHorizontal() // true
Random.line({allow: {vertical: false, horizontal: false, negative: false}}).slope.isStrictlyPositive() // true

Circles

Random.circle({radius: 5}).squareRadius.display // 25
Random.circle({squaredRadius: 5}).squareRadius.display // 5
Random.circle({pointsOnCircle: 8}).getPointsOnCircle().length >= 8 // true

pointsOnCircle asks for a circle with integer points on it, which makes the exercises easy to draw. The default is at least 8 points, applied when no radius is given.

Geometry in space

Random.point3().dimension // 3
Random.point3({plane: 'xy'}).z.isZero() // true
Random.point3({axis: 'x'}).y.isZero() // true
Random.vector3().dimension // 3

axis and plane act on the zero coordinates, and octant (1 to 8) on the signs. A line is drawn from a point A and a direction, and allow picks its kind: general, parallelXY, parallelXZ, parallelYZ, parallelX, parallelY and parallelZ.

Random.line3().direction.dimension // 3
Random.line3({allow: {parallelX: 1}}).direction.y.isZero() // true

Helpers

The helpers draw numbers and pick elements. They are used by the generators and are useful in an exercise on their own.

Random.number(5, 5) // 5
Math.abs(Random.numberSym(3)) <= 3 // true
[2, 3, 5, 7].includes(Random.prime(10)) // true
Random.triplet(5).includes(5) // true
Random.triplet(7) // null
Random.bool(1) // true
Random.bool(0) // false
Random.array([1, 2, 3], 2).length // 2
Random.item(['a']) // a
Random.shuffle([1, 2, 3]).length // 3
Random.item([]) // throws InvalidArgumentError

• number(from, to, exclude): an integer in [from, to], never one of exclude.
• numberSym(max, allowZero): an integer in [-max, max].
• prime(max): a prime strictly lower than max.
• triplet(target): a Pythagorean triplet of hypotenuse target, or null.
• bool(percent): true with the given probability (0.5 by default).
• array(arr, n) and shuffle(arr) do not modify the array they receive.

Options of each generator

These tables are generated from the TypeScript types and JSDoc of the library (npm run docs:sync), so they always match the code. The options of fraction are those of Random.fraction.

Random.fraction (coefficient options)

fraction(config?: RandomCoefficientConfig): Fraction

Generates a random fraction whose numerator and denominator are in [-max, max].

allow selects the signs the value may take: negative and positive (true by default) and zero (false by default, so 0 is never drawn unless allow: { zero: true }). The numerator is drawn uniformly among the allowed integers of [-max, max], so allow: { negative: false } gives a strictly positive value and allow: { positive: false } a strictly negative one.

relative: true forces an integer of either sign (denominator 1). The name follows Fraction.isRelative(); the former natural option, which was misleading (it allowed negatives), is rejected.

range keeps the value in an interval (a number d for [-|d|, |d|], or {min, max}). The signs of allow then only apply where the interval holds values of that sign, max defaults to the largest bound of the interval (at least 2; doubled when the interval stays at least 1 away from 0, which a smaller max could not reach with a non-integer fraction), and the value is drawn by rejection until it falls in the interval.

When relative: false (default), the denominator is chosen uniformly among values in [2, max] that do not divide the numerator (ensuring a non-integer result). If no such value exists within [2, max], the denominator falls back to 1.

Option	Type	Default	Description
max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
reduced	boolean	true	Reduce the fraction (default true).
range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
range.min (required)	number		See range.
range.max (required)	number		See range.
allow.zero	boolean	false	Allow the value 0 (default false).
allow.negative	boolean	true	Allow negative values (default true).
allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.

Errors

• {InvalidArgumentError} if allow excludes every value (e.g. negative and positive set to false while zero is left to false).
• {InvalidArgumentError} if the configuration contains the former natural option (renamed relative).
• {InvalidArgumentError} if range is invalid, leaves no value allowed by allow (or no integer with relative), or if no value falls in it within MAX_ATTEMPTS draws (widen range or raise max).

Random.monom

monom(config?: RandomMonomConfig): Monom

Generates a random Monom (a single term such as 3x² or -½xy).

fraction controls the coefficient generation strategy:

• false (default) — integer coefficient (relative: true passed to rndFraction).
• true — fractional coefficient allowed.
• RandomCoefficientConfig object — full control over the coefficient (max, reduced, allow.negative, allow.zero…). Values are deep-merged over the internal defaults.

Multi-variable degree distribution: when variables contains more than one variable, the degree units are distributed by drawing a random variable at each step and incrementing its exponent. This produces a multinomial distribution — for degree: 2 and variables: 'xy', xy is twice as probable as x² or y². Duplicate variables in variables are silently deduplicated before distribution.

Option	Type	Default	Description
degree	number	2	Total degree, a non-negative integer (default 2).
fraction	boolean | RandomCoefficientConfig	false	Coefficient: false (default) gives an integer, true allows fractions, an object gives full control over the coefficient.
variables	string	'x'	Variables of the monom, one lowercase letter each, duplicates ignored (default 'x'). With several variables, the degree is spread randomly.
allow.zero	boolean	false	Allow a zero coefficient (default false).

The fraction option takes the coefficient options of Random.fraction.

Errors

• {InvalidArgumentError} if variables is not a non-empty string of lowercase letters.
• {InvalidArgumentError} if degree is negative or not an integer.

Random.polynom

polynom(config?: RandomPolynomConfig): Polynom

Generates a random polynomial of the given degree.

allow.nullMonom — when true (default), non-leading monomials may have a zero coefficient (removed by reduce()); when false, every term from degree 0 to degree is guaranteed non-zero.

allow.negativeLeading — when false (default), the leading coefficient is always positive; the whole polynomial is negated if necessary.

allow.commonFactor — when false, the polynomial is retried until the GCD of all integer coefficients equals 1 (primitive polynomial). Ignored when fraction is not false (fractional coefficients).

numberOfMonoms — limits the number of terms by randomly removing non-leading monomials after generation. Silently ignored when the generated polynomial already has fewer terms than requested.

factorable: true — delegates to the internal rndFactorablePolynom: produces a product of degree linear factors with an optional common integer constant (see commonConstant).

commonConstant — controls the common constant factor for factorable polynomials:

• undefined (default): a random non-unit integer constant is sometimes added.
• false: no constant factor is ever added.
• true: a constant factor with |k| ≥ 2 is always added.

allow.commonFactor: false also applies to factorable: no constant factor is added, and the integer coefficients of the product have no common divisor (the content is divided out). It contradicts commonConstant: true, which throws.

Option	Type	Default	Description
commonConstant	boolean	undefined	Only for factorable: true. undefined (default): a non-unit integer constant factor is sometimes added; false: never; true: always, with an absolute value of at least 2. Contradicts allow.commonFactor: false (which asks for no common factor at all) and throws with it.
degree	number	2	Degree, a non-negative integer (default 2).
factorable	boolean	false	Build the polynom as a product of degree linear factors (default false).
fraction	boolean | RandomCoefficientConfig	false	Coefficients: false (default) gives integers, true fractions, an object gives full control.
variables	string	'x'	Variables of the polynom, one lowercase letter each (default 'x').
numberOfMonoms	number	0': no limit	Maximum number of terms (default 0: no limit). Ignored when the polynom already has fewer terms.
unit	boolean	false	Force a leading coefficient equal to 1 (default false).
allow.nullMonom	boolean	true	Non-leading terms may have a zero coefficient, i.e. be absent (default true).
allow.negativeLeading	boolean	false': the polynom is negated if needed	Allow a negative leading coefficient (default false: the polynom is negated if needed).
allow.commonFactor	boolean	true	Allow a common factor between the integer coefficients (default true); false divides it out, and with factorable also adds no constant factor. The division is skipped with fractions.

The fraction option takes the coefficient options of Random.fraction.

Errors

• {InvalidArgumentError} if degree is not a non-negative integer.
• {InvalidArgumentError} if variables is not a non-empty string of lowercase letters.
• {InvalidArgumentError} if commonConstant is true while allow.commonFactor is false (with factorable).

Random.equation

equation(config?: RandomEquationConfig): Equation

Generates a random polynomial equation.

Modes (evaluated in order):

• solution.everything: true — degenerate P = P (infinite solutions, 0 = 0).
• solution.nothing: true — degenerate P+k = P, k ≠ 0 (no solution, ∅).
• factorable: true or solution.count set — P built as a product of controlled factors.
• Default — random P(x) = 0.

solution.count — exact number of distinct real solutions (0..degree). When (degree−count) is odd, one root is doubled (still one distinct solution). count=0 with odd degree is impossible by IVT and throws.

Irreducible quadratic factors — when needed to fill remaining degree after linear factors, uses ax²+c (a,c > 0), which always has negative discriminant.

solution.relative: true — forces integer roots of either sign (unit leading coefficient per factor).

solution.range — the interval of the solutions (default [-5, 5]), also used for the constant that nothing adds; fractional solutions follow fraction within it.

solution.allowZero — allows 0 as a root (default true). It is in solution, not in allow, because it constrains the solutions of the equation rather than its coefficients.

shuffle: true — adds a random polynomial Q (same degree/variables/fraction) to both sides: P = 0 becomes P+Q = Q.

Option	Type	Default	Description
degree	number	1	Degree, a non-negative integer (default 1).
variables	string	'x'	Variables of the equation, one lowercase letter each (default 'x').
fraction	boolean | RandomCoefficientConfig	false	Coefficients: false (default) gives integers, true fractions, an object gives full control.
unit	boolean	false	Force a leading coefficient equal to 1 (default false).
factorable	boolean	false	Build the equation from a product of factors, so that its solutions are controlled (default false).
shuffle	boolean	false	Add a random polynom to both sides: P = 0 becomes P + Q = Q (default false).
solution.count	number	unset	Exact number of distinct real solutions, from 0 to degree. Implies a factored construction (default: unset, the number is free).
solution.allowZero	boolean	true	Allow 0 as a solution (default true). It lives in solution rather than in allow: it constrains the solutions of the equation, not its coefficients.
solution.relative	boolean	false	Force integer solutions of either sign, like relative for a fraction (default false).
solution.range	RandomRange	5	Interval of the solutions, and of the constant added by nothing (default 5, i.e. [-5, 5]): a number d means [-|d|, |d|], {min, max} gives explicit bounds. Fractional solutions follow the fraction configuration, within this interval.
solution.nothing	number | boolean	false	Equation without solution: true, false (default), or a probability between 0 and 1.
solution.everything	number | boolean	false	Equation true for every value: true, false (default), or a probability between 0 and 1.
allow.negativeLeading	boolean	false	Allow a negative leading coefficient (default false).
allow.commonFactor	boolean	true	Allow a common factor between the integer coefficients (default true).

The fraction option takes the coefficient options of Random.fraction.

Errors

• {InvalidArgumentError} if degree is not a non-negative integer.
• {InvalidArgumentError} if variables is not a non-empty string of lowercase letters, or holds several variables while factorable or solution.count is set (the solutions are those of a single variable).
• {InvalidArgumentError} if solution.nothing or solution.everything is neither a boolean nor a probability between 0 and 1.
• {InvalidArgumentError} if solution.range is invalid, or holds only 0 while solution.nothing can be drawn.
• {InvalidArgumentError} if solution.count is out of range or impossible for the given degree.
• {InvalidArgumentError} if the configuration contains the former solution.integer option (renamed solution.relative).

Random.point

point(config?: RandomGeometryPointConfig): Point

Generates a random 2D Point.

Each coordinate is drawn in the interval range ∩ quadrant, subject to a zero rule given by axis. The two constraints are independent: axis acts on zero, quadrant acts on sign.

axis (default null):

• 'x' / 'y' — the point is on that axis (y = 0 / x = 0); the other coordinate is free, so the origin is possible unless allow.origin is false.
• true — on one of the two axes, chosen at random.
• false — on no axis: no coordinate is zero.
• null — unconstrained: a coordinate may be zero.

quadrant — a quadrant 1..4, or an array of quadrants (union). Axes are included: quadrant 1 means x >= 0 and y >= 0. With an array, one quadrant is chosen uniformly, then the point is drawn in it (uniform over the quadrants, not over the surface when range is asymmetric). Combine with axis: false for points strictly inside the quadrant.

range — a number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.

fraction — false (default) draws integers; true draws fractions; a RandomCoefficientConfig gives full control. Its allow (zero, negative, positive) is ignored (it is driven by axis, quadrant and range); its max, when given, bounds the numerator and denominator instead of the range. Fractions are drawn by rejection until they fall in the interval.

Option	Type	Default	Description
axis	boolean | "x" | "y" | null	null	Where the point lies relative to the axes (default null). - 'x': on the x-axis (y = 0); 'y': on the y-axis (x = 0). - true: on one of the two axes, chosen at random. - false: on no axis (no coordinate is zero). - null: unconstrained (a coordinate may be zero).
fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
range.min (required)	number		See range.
range.max (required)	number		See range.
quadrant	Quadrant | Quadrant[] | null	null	Restricts the point to one quadrant, or to a union of quadrants (default null). Axes belong to the quadrants: quadrant 1 means x >= 0 and y >= 0. With several quadrants, one of them is chosen uniformly, then the point is drawn in it.
allow.origin	boolean	true	false excludes the point (0, 0) (default true).

The fraction option takes the coefficient options of Random.fraction.

Errors

• {InvalidArgumentError} if axis, quadrant or range is invalid.
• {InvalidArgumentError} if the constraints are incompatible (e.g. axis: 'x' with a range that excludes 0, or a quadrant disjoint from the range) — checked for every alternative (each quadrant, each axis of axis: true) before drawing, so the error does not depend on the random choice — or if they cannot be satisfied in MAX_ATTEMPTS draws.

Random.point3

point3(config?: RandomGeometryPoint3Config): Point

Generates a random 3D Point.

Each coordinate is drawn in the interval range ∩ octant, subject to a zero rule given by axis or plane. The constraints are independent: axis and plane act on zero, octant acts on sign.

axis (default null):

• 'x' / 'y' / 'z' — the point is on that axis (the two other coordinates are zero);
• true — on one of the three axes, chosen at random;
• false — no coordinate is zero;
• null — unconstrained: a coordinate may be zero.

plane (default null) — 'xy' (z = 0), 'xz' (y = 0), 'yz' (x = 0), or true for one of them chosen at random. The two other coordinates are free, so they may be zero. Exclusive with axis.

octant — an octant 1..8, or an array of octants (union). Axes and planes are included: octant 1 means x >= 0, y >= 0 and z >= 0. Octants 1 to 4 are the quadrants 1 to 4 with z >= 0; octants 5 to 8 are the same quadrants with z <= 0. With an array, one octant is chosen uniformly, then the point is drawn in it. Combine with axis: false for points strictly inside the octant.

range — a number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.

fraction — false (default) draws integers; true draws fractions; a RandomCoefficientConfig gives full control (its allow is ignored, as for rndPoint; its max, when given, bounds the numerator and the denominator instead of the range).

allow.origin (default true) — false excludes the point (0, 0, 0).

Option	Type	Default	Description
axis	boolean | "x" | "y" | "z" | null	null	Where the point lies relative to the axes (default null). - 'x', 'y', 'z': on that axis (the two other coordinates are zero). - true: on one of the three axes, chosen at random. - false: on no axis and in no coordinate plane (no coordinate is zero). - null: unconstrained (a coordinate may be zero). Exclusive with plane.
plane	boolean | "xy" | "xz" | "yz" | null	null	Coordinate plane containing the point (default null). - 'xy' (z = 0), 'xz' (y = 0), 'yz' (x = 0): the other two coordinates are free. - true: in one of the three planes, chosen at random. - false / null: no constraint. Exclusive with axis.
fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
range.min (required)	number		See range.
range.max (required)	number		See range.
octant	Octant | Octant[] | null	null	Restricts the point to one octant, or to a union of octants (default null). Axes and planes belong to the octants. With several octants, one of them is chosen uniformly, then the point is drawn in it.
allow.origin	boolean	true	false excludes the point (0, 0, 0) (default true).

The fraction option takes the coefficient options of Random.fraction.

Errors

• {InvalidArgumentError} if axis, plane, octant or range is invalid, or if axis and plane are combined.
• {InvalidArgumentError} if the constraints are incompatible (e.g. axis: 'x' with a range that excludes 0, or an octant disjoint from the range) — checked for every alternative before drawing, so the error does not depend on the random choice of an axis, a plane or an octant.
• {InvalidArgumentError} if the constraints cannot be satisfied in MAX_ATTEMPTS draws.

Random.vector

vector(config?: RandomGeometryVectorConfig): Vector

Generates a random 2D Vector.

The components are drawn like the coordinates of rndPoint, with the same options: axis, quadrant, range and fraction (see rndPoint). Two options are specific to vectors (see RandomVectorOptions in rndTypes.ts): allow.zero (the null vector is excluded by default; it replaces the allow.origin of points) and primitive (integer components with no common divisor).

Option	Type	Default	Description
axis	boolean | "x" | "y" | null	null	Where the point lies relative to the axes (default null). - 'x': on the x-axis (y = 0); 'y': on the y-axis (x = 0). - true: on one of the two axes, chosen at random. - false: on no axis (no coordinate is zero). - null: unconstrained (a coordinate may be zero).
fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
range.min (required)	number		See range.
range.max (required)	number		See range.
quadrant	Quadrant | Quadrant[] | null	null	Restricts the point to one quadrant, or to a union of quadrants (default null). Axes belong to the quadrants: quadrant 1 means x >= 0 and y >= 0. With several quadrants, one of them is chosen uniformly, then the point is drawn in it.
primitive	boolean	false	Integer components with no common divisor, e.g. (1, 2) and never (2, 4) (default false). Requires integers.
allow.zero	boolean	false	true allows the null vector (default false).

The fraction option takes the coefficient options of Random.fraction.

Errors

• {InvalidArgumentError} if allow.origin is given (use allow.zero), if allow.zero or primitive is not a boolean, or if primitive is combined with fractions.
• {InvalidArgumentError} for any invalid or incompatible point option (see rndPoint), or if no primitive vector within range is found.

Random.vector3

vector3(config?: RandomGeometryVector3Config): Vector

Generates a random 3D Vector.

The components are drawn like the coordinates of rndPoint3, with the same options: axis, plane, octant, range and fraction (see rndPoint3). Two options are specific to vectors (see RandomVectorOptions in rndTypes.ts): allow.zero (the null vector is excluded by default; it replaces the allow.origin of points) and primitive (integer components with no common divisor).

Option	Type	Default	Description
axis	boolean | "x" | "y" | "z" | null	null	Where the point lies relative to the axes (default null). - 'x', 'y', 'z': on that axis (the two other coordinates are zero). - true: on one of the three axes, chosen at random. - false: on no axis and in no coordinate plane (no coordinate is zero). - null: unconstrained (a coordinate may be zero). Exclusive with plane.
fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
range.min (required)	number		See range.
range.max (required)	number		See range.
plane	boolean | "xy" | "xz" | "yz" | null	null	Coordinate plane containing the point (default null). - 'xy' (z = 0), 'xz' (y = 0), 'yz' (x = 0): the other two coordinates are free. - true: in one of the three planes, chosen at random. - false / null: no constraint. Exclusive with axis.
octant	Octant | Octant[] | null	null	Restricts the point to one octant, or to a union of octants (default null). Axes and planes belong to the octants. With several octants, one of them is chosen uniformly, then the point is drawn in it.
primitive	boolean	false	Integer components with no common divisor, e.g. (1, 2) and never (2, 4) (default false). Requires integers.
allow.zero	boolean	false	true allows the null vector (default false).

The fraction option takes the coefficient options of Random.fraction.

Errors

• {InvalidArgumentError} if allow.origin is given (use allow.zero), if allow.zero or primitive is not a boolean, or if primitive is combined with fractions.
• {InvalidArgumentError} for any invalid or incompatible point option (see rndPoint3), or if no primitive vector within range is found.

Random.line

line(config?: RandomGeometryLineConfig): Line

Generates a random Line, built from a point A and a slope.

A — a Point fixes the point exactly; an object is the configuration of rndPoint (default: its own defaults). The legacy {x, y} form is rejected: use new Point(x, y).

slope:

• an exact value (2, '-3/2', Fraction) gives a line with exactly that slope (0 is horizontal);
• { fraction } draws a random slope: false for an integer, true for a fraction (default), or a RandomCoefficientConfig such as { max: 5 }. The sign of the coefficient configuration is overridden by the kind of line drawn (see allow).

allow — the kind of line to draw, for a random slope. Each of vertical, horizontal (zero slope), positive and negative (sign of the slope) is false (never), a number in [0, 1] (probability of that kind) or true (default). true means 5 % for vertical and horizontal, and an equal share of what remains for positive and negative. An explicit number takes precedence over true, and probabilities that do not add up are normalized. { vertical: 1 } always gives a vertical line; { vertical: false, horizontal: false, negative: false } always gives a positive slope.

Option	Type	Default	Description
A	RandomGeometryPointConfig | Point	its own defaults	Point on the line: a Point fixes it exactly (new Point(1, 2)); an object is the configuration of the random point drawn by rndPoint (default: its own defaults).
A.axis	boolean | "x" | "y" | null	null	Where the point lies relative to the axes (default null). - 'x': on the x-axis (y = 0); 'y': on the y-axis (x = 0). - true: on one of the two axes, chosen at random. - false: on no axis (no coordinate is zero). - null: unconstrained (a coordinate may be zero).
A.fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
A.fraction.max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
A.fraction.relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
A.fraction.reduced	boolean	true	Reduce the fraction (default true).
A.fraction.range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
A.fraction.range.min (required)	number		See A.fraction.range.
A.fraction.range.max (required)	number		See A.fraction.range.
A.fraction.allow.zero	boolean	false	Allow the value 0 (default false).
A.fraction.allow.negative	boolean	true	Allow negative values (default true).
A.fraction.allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.
A.range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
A.range.min (required)	number		See A.range.
A.range.max (required)	number		See A.range.
A.quadrant	Quadrant | Quadrant[] | null	null	Restricts the point to one quadrant, or to a union of quadrants (default null). Axes belong to the quadrants: quadrant 1 means x >= 0 and y >= 0. With several quadrants, one of them is chosen uniformly, then the point is drawn in it.
A.allow.origin	boolean	true	false excludes the point (0, 0) (default true).
slope	FractionOrRandom	a random slope	Slope of the line (default: a random slope, as with { fraction: true }). - an exact value (2, '-3/2', new Fraction(1, 2)): the line has exactly that slope. Prefer a string for a non-terminating fraction ('1/3', not 0.333). Incompatible with an explicit allow. - { fraction }: a random slope, false for an integer, true for a fraction, or a RandomCoefficientConfig (e.g. max). The sign comes from allow.positive / allow.negative.
slope.fraction	boolean | RandomCoefficientConfig		See slope.
slope.fraction.max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
slope.fraction.relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
slope.fraction.reduced	boolean	true	Reduce the fraction (default true).
slope.fraction.range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
slope.fraction.range.min (required)	number		See slope.fraction.range.
slope.fraction.range.max (required)	number		See slope.fraction.range.
slope.fraction.allow.zero	boolean	false	Allow the value 0 (default false).
slope.fraction.allow.negative	boolean	true	Allow negative values (default true).
slope.fraction.allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.
allow	{ vertical?: boolean | number; horizontal?: boolean | number; positive?: boolean | number; negative?: boolean | number; }	true	Kind of line that may be drawn, for a random slope. Each entry is false (never), a number between 0 and 1 (probability of that kind), or true (default): - vertical / horizontal (zero slope): true means a fixed probability of 5 %; - positive / negative (slope sign): true shares equally what the others leave. Probabilities that do not add up are normalized, and an explicit number takes precedence over true. Examples: { negative: false, horizontal: false, vertical: false } always gives a positive slope; { vertical: 1 } always gives a vertical line.
allow.vertical	number | boolean	true	See allow.
allow.horizontal	number | boolean	true	See allow.
allow.positive	number | boolean	true	See allow.
allow.negative	number | boolean	true	See allow.

Errors

• {InvalidArgumentError} if A, slope or an allow entry is invalid.
• {InvalidArgumentError} if allow excludes every kind of line.
• {InvalidArgumentError} if an exact slope is combined with an explicit allow.

Random.line3

line3(config?: RandomGeometryLine3Config): Line3

Generates a random 3D Line3, built from a point A and a direction vector.

A — a 3D Point fixes the point exactly; an object is the configuration of rndPoint3 (default: its own defaults). The legacy {x, y, z} form is rejected: use new Point(x, y, z).

direction — a non-null 3D Vector fixes the direction exactly; an object is the configuration of rndVector3 (range, octant, fraction, primitive…; default: its own defaults). The legacy {x, y, z} form is rejected: use new Vector(x, y, z). The direction is never null.

allow — the kind of line to draw, for a random direction (a, b, c). The kinds are exclusive:

• general: no zero component;
• parallelXY (c = 0), parallelXZ (b = 0), parallelYZ (a = 0): exactly one zero component, i.e. parallel to that coordinate plane but to no axis;
• parallelX (b = c = 0), parallelY, parallelZ: two zero components, i.e. parallel to that axis.

Each is false (never), a number in [0, 1] (probability of that kind) or true (default). true means 5 % for each parallelXY / parallelXZ / parallelYZ, 2 % for each parallelX / parallelY / parallelZ, and for general what the others leave. An explicit number takes precedence over true, and probabilities that do not add up are normalized. { parallelXY: 1 } always gives a line parallel to the xy plane.

The kind of line imposes the zeros of the direction, so the axis and plane of a direction configuration are overridden (its octant, range and fraction still apply). A kind allowed by true that the direction configuration makes impossible (e.g. a range that excludes 0, for a kind that needs a zero) is skipped.

Option	Type	Default	Description
A	RandomGeometryPoint3Config | Point	its own defaults	Point on the line: a 3D Point fixes it exactly (new Point(1, 2, 3)); an object is the configuration of the random point drawn by rndPoint3 (default: its own defaults).
A.axis	boolean | "x" | "y" | "z" | null	null	Where the point lies relative to the axes (default null). - 'x', 'y', 'z': on that axis (the two other coordinates are zero). - true: on one of the three axes, chosen at random. - false: on no axis and in no coordinate plane (no coordinate is zero). - null: unconstrained (a coordinate may be zero). Exclusive with plane.
A.plane	boolean | "xy" | "xz" | "yz" | null	null	Coordinate plane containing the point (default null). - 'xy' (z = 0), 'xz' (y = 0), 'yz' (x = 0): the other two coordinates are free. - true: in one of the three planes, chosen at random. - false / null: no constraint. Exclusive with axis.
A.fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
A.fraction.max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
A.fraction.relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
A.fraction.reduced	boolean	true	Reduce the fraction (default true).
A.fraction.range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
A.fraction.range.min (required)	number		See A.fraction.range.
A.fraction.range.max (required)	number		See A.fraction.range.
A.fraction.allow.zero	boolean	false	Allow the value 0 (default false).
A.fraction.allow.negative	boolean	true	Allow negative values (default true).
A.fraction.allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.
A.range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
A.range.min (required)	number		See A.range.
A.range.max (required)	number		See A.range.
A.octant	Octant | Octant[] | null	null	Restricts the point to one octant, or to a union of octants (default null). Axes and planes belong to the octants. With several octants, one of them is chosen uniformly, then the point is drawn in it.
A.allow.origin	boolean	true	false excludes the point (0, 0, 0) (default true).
direction	RandomGeometryVector3Config | Vector	its own defaults	Direction of the line: a non-null 3D Vector fixes it exactly (new Vector(1, 0, 2); incompatible with an explicit allow); an object is the configuration of the random vector drawn by rndVector3 (default: its own defaults). The direction is never null. Its axis and plane are overridden by the kind of line drawn (see allow), and its allow.zero must not be true.
direction.axis	boolean | "x" | "y" | "z" | null	null	Where the point lies relative to the axes (default null). - 'x', 'y', 'z': on that axis (the two other coordinates are zero). - true: on one of the three axes, chosen at random. - false: on no axis and in no coordinate plane (no coordinate is zero). - null: unconstrained (a coordinate may be zero). Exclusive with plane.
direction.fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
direction.fraction.max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
direction.fraction.relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
direction.fraction.reduced	boolean	true	Reduce the fraction (default true).
direction.fraction.range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
direction.fraction.range.min (required)	number		See direction.fraction.range.
direction.fraction.range.max (required)	number		See direction.fraction.range.
direction.fraction.allow.zero	boolean	false	Allow the value 0 (default false).
direction.fraction.allow.negative	boolean	true	Allow negative values (default true).
direction.fraction.allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.
direction.range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
direction.range.min (required)	number		See direction.range.
direction.range.max (required)	number		See direction.range.
direction.plane	boolean | "xy" | "xz" | "yz" | null	null	Coordinate plane containing the point (default null). - 'xy' (z = 0), 'xz' (y = 0), 'yz' (x = 0): the other two coordinates are free. - true: in one of the three planes, chosen at random. - false / null: no constraint. Exclusive with axis.
direction.octant	Octant | Octant[] | null	null	Restricts the point to one octant, or to a union of octants (default null). Axes and planes belong to the octants. With several octants, one of them is chosen uniformly, then the point is drawn in it.
direction.primitive	boolean	false	Integer components with no common divisor, e.g. (1, 2) and never (2, 4) (default false). Requires integers.
direction.allow.zero	boolean	false	true allows the null vector (default false).
allow	{ general?: boolean | number; parallelXY?: boolean | number; parallelXZ?: boolean | number; parallelYZ?: boolean | number; parallelX?: boolean | number; parallelY?: boolean | number; parallelZ?: boolean | number; }	true	Kind of line that may be drawn, for a random direction (a, b, c). The kinds are exclusive; each entry is false (never), a number between 0 and 1 (probability of that kind), or true (default): - general: no zero component (the line is parallel to no coordinate plane). true shares what the other kinds leave; - parallelXY (c = 0), parallelXZ (b = 0), parallelYZ (a = 0): exactly one zero component, i.e. parallel to that coordinate plane but to no axis. true means 5 %; - parallelX (b = c = 0), parallelY, parallelZ: two zero components, i.e. parallel to that axis. true means 2 %. Probabilities that do not add up are normalized, and an explicit number takes precedence over true. A kind allowed by true that the direction configuration makes impossible (e.g. a range excluding 0 for a kind that needs a zero) is skipped; the same kind asked by an explicit number throws.
allow.general	number | boolean	true	See allow.
allow.parallelXY	number | boolean	true	See allow.
allow.parallelXZ	number | boolean	true	See allow.
allow.parallelYZ	number | boolean	true	See allow.
allow.parallelX	number | boolean	true	See allow.
allow.parallelY	number | boolean	true	See allow.
allow.parallelZ	number | boolean	true	See allow.

Errors

• {InvalidArgumentError} if A, direction or an allow entry is invalid, or if direction.allow.zero is true.
• {InvalidArgumentError} if allow excludes every kind of line, or if a kind asked by an explicit number is impossible with the direction configuration.
• {InvalidArgumentError} if an exact direction is null, or combined with an explicit allow.

Random.circle

circle(config?: RandomGeometryCircleConfig): Circle

Generates a random Circle, from a center and a squared radius.

center — configuration of rndPoint (default: its own defaults).

radius / squaredRadius (exclusive; default: a random squaredRadius) — an exact value (5, '5/2') or { fraction } to draw it at random. squaredRadius allows irrational radii (5 gives x² + y² = 5, radius √5). A random integer goes from 1 to 5 (radius) or 1 to 25 (squaredRadius), unless fraction is an object giving max and relative: true. An object fraction without relative: true gives fractions.

pointsOnCircle — the circle has at least min points whose offsets from the center are integers, so their coordinates are exact (Circle.getPointsOnCircle returns them). A number n means { min: n }. The default is { min: 8 }, applied only when neither radius is given; otherwise it applies only if set explicitly. The candidates are enumerated and one is picked uniformly: the default gives the squared radii 5, 10, 13, 17, 20 and 25. fraction: true (fractional offsets) is not implemented yet.

Option	Type	Default	Description
center	RandomGeometryPointConfig	its own defaults	Options of the center, drawn by rndPoint (default: its own defaults).
center.axis	boolean | "x" | "y" | null	null	Where the point lies relative to the axes (default null). - 'x': on the x-axis (y = 0); 'y': on the y-axis (x = 0). - true: on one of the two axes, chosen at random. - false: on no axis (no coordinate is zero). - null: unconstrained (a coordinate may be zero).
center.fraction	boolean | RandomCoefficientConfig	false	false (default): integer coordinates; true: fractions; object: full control over the fractions.
center.fraction.max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
center.fraction.relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
center.fraction.reduced	boolean	true	Reduce the fraction (default true).
center.fraction.range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
center.fraction.range.min (required)	number		See center.fraction.range.
center.fraction.range.max (required)	number		See center.fraction.range.
center.fraction.allow.zero	boolean	false	Allow the value 0 (default false).
center.fraction.allow.negative	boolean	true	Allow negative values (default true).
center.fraction.allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.
center.range	RandomRange	10	Interval of the coordinates (default 10). A number d means [-|d|, |d|] (so 10 and -10 are equivalent); {min, max} gives explicit bounds.
center.range.min (required)	number		See center.range.
center.range.max (required)	number		See center.range.
center.quadrant	Quadrant | Quadrant[] | null	null	Restricts the point to one quadrant, or to a union of quadrants (default null). Axes belong to the quadrants: quadrant 1 means x >= 0 and y >= 0. With several quadrants, one of them is chosen uniformly, then the point is drawn in it.
center.allow.origin	boolean	true	false excludes the point (0, 0) (default true).
radius	FractionOrRandom	is a random 'squaredRadius	Radius of the circle: an exact value (5, '5/2'), or { fraction } for a random one (fraction: false gives an integer from 1 to 5 unless max is given, true a fraction). Exclusive with squaredRadius. The default is a random squaredRadius.
radius.fraction	boolean | RandomCoefficientConfig		See radius.
radius.fraction.max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
radius.fraction.relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
radius.fraction.reduced	boolean	true	Reduce the fraction (default true).
radius.fraction.range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
radius.fraction.range.min (required)	number		See radius.fraction.range.
radius.fraction.range.max (required)	number		See radius.fraction.range.
radius.fraction.allow.zero	boolean	false	Allow the value 0 (default false).
radius.fraction.allow.negative	boolean	true	Allow negative values (default true).
radius.fraction.allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.
squaredRadius	FractionOrRandom	a random integer	Squared radius of the circle (default: a random integer, see pointsOnCircle; the radius is then its square root, possibly irrational: 5 gives x² + y² = 5). Same forms as radius; the random integer ranges from 1 to 25 unless max is given. An object fraction gives fractions unless it sets relative: true.
squaredRadius.fraction	boolean | RandomCoefficientConfig		See squaredRadius.
squaredRadius.fraction.max	number	10	Bound (absolute value) of the numerator and of the denominator (default 10).
squaredRadius.fraction.relative	boolean	false	true forces an integer of either sign (denominator 1): the name follows Fraction.isRelative() (a "natural" number would be non-negative). Default false.
squaredRadius.fraction.reduced	boolean	true	Reduce the fraction (default true).
squaredRadius.fraction.range	RandomRange	none	Interval of the value: a number d means [-|d|, |d|], {min, max} gives explicit bounds (default: none, the value is only bounded by max). Combined with allow: a sign is possible only if the interval holds values of that sign. max then defaults to the largest bound of the interval, at least 2 (doubled when the interval stays at least 1 away from 0), so that a small interval still gets fractions. Where a generator drives the interval itself (the coordinates of a point, the radius…), its own interval replaces this one.
squaredRadius.fraction.range.min (required)	number		See squaredRadius.fraction.range.
squaredRadius.fraction.range.max (required)	number		See squaredRadius.fraction.range.
squaredRadius.fraction.allow.zero	boolean	false	Allow the value 0 (default false).
squaredRadius.fraction.allow.negative	boolean	true	Allow negative values (default true).
squaredRadius.fraction.allow.positive	boolean	true	Allow positive values (default true). With negative: false and zero left to false nothing is left: it throws.
pointsOnCircle	number | { min?: number; fraction?: boolean; }	{ min: 8, fraction: false }	Wanted number of points of the circle with exact coordinates: n is shorthand for { min: n }. - min: the circle has at least that many points whose offsets from the center are integers (the coordinates stay exact fractions when the center is fractional). A count is always a multiple of 4. - fraction: reserved for points with fractional offsets; true is not implemented yet. Default { min: 8, fraction: false }, applied only when neither radius nor squaredRadius is given; once one of them is given, pointsOnCircle applies only if set explicitly (an exact radius that does not reach min then throws, and so does a fractional random radius, which has no integer points).
pointsOnCircle.min	number		See pointsOnCircle.
pointsOnCircle.fraction	boolean		See pointsOnCircle.

Errors

• {InvalidArgumentError} if radius and squaredRadius are both given, or if a radius, max or pointsOnCircle is invalid.
• {InvalidArgumentError} if no candidate has min points, if an exact radius that was requested with pointsOnCircle has fewer, or if a random fractional radius is requested with min > 0 (it has no integer points).
• {NotImplementedError} if pointsOnCircle.fraction is true.