From 9e6f648f0bcffc2ed7d6e4a247ae258f86757e18 Mon Sep 17 00:00:00 2001 From: filifa Date: Wed, 17 Sep 2025 21:02:05 -0400 Subject: [PATCH] add more help text --- cmd/convergents.go | 11 ++++++++--- cmd/discreteLog.go | 10 +++++++--- cmd/divisor.go | 7 +++++-- cmd/divisors.go | 15 ++++++++++++--- cmd/gcd.go | 11 +++++++---- cmd/jacobi.go | 12 ++++++++++-- cmd/mobius.go | 12 +++++++++--- cmd/modInverse.go | 8 +++++--- cmd/partitions.go | 16 +++++++++++++--- cmd/pell.go | 9 ++++++--- cmd/shoelace.go | 14 +++++++++++--- cmd/sqrtRepetend.go | 15 +++++++++++---- cmd/stirling.go | 20 +++++++++++++++++--- cmd/totient.go | 8 +++++--- 14 files changed, 126 insertions(+), 42 deletions(-) diff --git a/cmd/convergents.go b/cmd/convergents.go index e5b9bda..c164b08 100644 --- a/cmd/convergents.go +++ b/cmd/convergents.go @@ -49,9 +49,14 @@ func convergents(cmd *cobra.Command, args []string) { var convergentsCmd = &cobra.Command{ Use: "convergents N N [N ...]", Short: "Compute convergents of a periodic continued fraction", - Long: `Compute convergents of a periodic continued fraction.`, - Args: cobra.MinimumNArgs(2), - Run: convergents, + Long: `Compute convergents of a periodic continued fraction. + +The first number given is the integer part. The following numbers give the repetend of the continued fraction. + +This will output convergents infinitely. Try piping to head to only output a certain number of convergents, like this: +mathtools convergents 3 2 6 | head -n 5`, + Args: cobra.MinimumNArgs(2), + Run: convergents, } func init() { diff --git a/cmd/discreteLog.go b/cmd/discreteLog.go index 2225bc4..1da619d 100644 --- a/cmd/discreteLog.go +++ b/cmd/discreteLog.go @@ -119,10 +119,14 @@ func discreteLog(cmd *cobra.Command, args []string) { // discreteLogCmd represents the discreteLog command var discreteLogCmd = &cobra.Command{ - Use: "discrete-log", + Use: "discrete-log -b N -m N -e N", Short: "Compute the discrete logarithm", - Long: `Compute the discrete logarithm.`, - Run: discreteLog, + Long: `Compute the discrete logarithm. + +Given a base b, modulus m, and element e, compute a value k such that b^k = e (mod m). + +Note that no efficient method of finding the discrete logarithm is currently known. For slightly improved performance, the order of the group (i.e. the totient of m) can be provided.`, + Run: discreteLog, } func init() { diff --git a/cmd/divisor.go b/cmd/divisor.go index 580b43a..4a00a1f 100644 --- a/cmd/divisor.go +++ b/cmd/divisor.go @@ -59,8 +59,11 @@ func divisorSum(cmd *cobra.Command, args []string) { var divisorCmd = &cobra.Command{ Use: "divisor N [N ...]", Short: "Compute the divisor summatory function", - Long: `Compute the divisor summatory function.`, - Run: divisorSum, + Long: `Compute the divisor summatory function. + +For each argument n, compute D(n) = d(1) + d(2) + d(3) + ... + d(n), where d(n) is the number of divisors of n.`, + Args: cobra.MinimumNArgs(1), + Run: divisorSum, } func init() { diff --git a/cmd/divisors.go b/cmd/divisors.go index 4d57e05..8ad1ffb 100644 --- a/cmd/divisors.go +++ b/cmd/divisors.go @@ -103,10 +103,19 @@ func divisors(cmd *cobra.Command, args []string) { // divisorsCmd represents the divisors command var divisorsCmd = &cobra.Command{ - Use: "divisors", + Use: "divisors -n N", Short: "Compute the divisor function for all numbers less than n", - Long: `Compute the divisor function for all numbers less than n.`, - Run: divisors, + Long: `Compute the divisor function for all numbers less than n. + +sigma_x(n) computes the sum of the xth powers of the divisors of n. +For example, the divisors of 12 are 1, 2, 3, 4, 6, and 12. +sigma_0(12) = 6 +sigma_1(12) = 1 + 2 + 3 + 4 + 6 + 12 = 28 +sigma_2(12) = 1^2 + 2^2 + 3^2 + 4^2 + 6^2 + 12^2 = 210 + +This program computes sigma for all values less than the input n. +Provide the --exponent flag to set the desired exponent for each sum.`, + Run: divisors, } func init() { diff --git a/cmd/gcd.go b/cmd/gcd.go index 597466a..688a8f8 100644 --- a/cmd/gcd.go +++ b/cmd/gcd.go @@ -69,9 +69,12 @@ func gcd(cmd *cobra.Command, args []string) { var gcdCmd = &cobra.Command{ Use: "gcd N N [N ...]", Short: "Compute the greatest common denominator of a set of numbers", - Long: `Compute the greatest common denominator of a set of numbers.`, - Args: cobra.MinimumNArgs(2), - Run: gcd, + Long: `Compute the greatest common denominator of a set of numbers. + +Provide the --extended flag to also compute the Bézout coefficients, i.e. coefficients a,b,c,... such that +ax + by + cz + ... = gcd(x,y,z,...)`, + Args: cobra.MinimumNArgs(2), + Run: gcd, } func init() { @@ -87,5 +90,5 @@ func init() { // is called directly, e.g.: // gcdCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle") - gcdCmd.Flags().BoolVarP(&extended, "extended", "e", false, "also compute the Bezout coefficients") + gcdCmd.Flags().BoolVarP(&extended, "extended", "e", false, "also compute the Bézout coefficients") } diff --git a/cmd/jacobi.go b/cmd/jacobi.go index 9f6e964..476f884 100644 --- a/cmd/jacobi.go +++ b/cmd/jacobi.go @@ -51,8 +51,16 @@ func jacobi(cmd *cobra.Command, args []string) { var jacobiCmd = &cobra.Command{ Use: "jacobi -a A -n N", Short: "Compute the Jacobi symbol", - Long: `Compute the Jacobi symbol (a | n).`, - Run: jacobi, + Long: `Compute the Jacobi symbol (a | n). + +The Jacobi symbol is useful for studying quadratic residues. a is a quadratic residue modulo n if there exists a value x such that +x^2 = a (mod n) + +If a is a quadratic residue modulo n and gcd(a, n) = 1, then (a | n) = 1. +If (a | n) = -1, then a is a quadratic nonresidue modulo n. + +However, (a | n) = 1 does not guarantee that a is a quadratic residue modulo n.`, + Run: jacobi, } func init() { diff --git a/cmd/mobius.go b/cmd/mobius.go index c961a8c..2fabafa 100644 --- a/cmd/mobius.go +++ b/cmd/mobius.go @@ -73,10 +73,16 @@ func mobius(cmd *cobra.Command, args []string) { // mobiusCmd represents the mobius command var mobiusCmd = &cobra.Command{ - Use: "mobius", + Use: "mobius -n N", Short: "Compute the Möbius function for all numbers less than n", - Long: `Compute the Möbius function for all numbers less than n.`, - Run: mobius, + Long: `Compute the Möbius function for all numbers less than n. + +The Möbius function mu(n) is a multiplicative function defined as follows for prime p: +mu(p) = -1 +mu(p^k) = 0 for k > 1 + +This means for squarefree n, mu(n) = -1 if n has an odd number of prime factors and mu(n) = 1 if n has an even number of prime factors. mu(n) = 0 if n is not squarefree.`, + Run: mobius, } func init() { diff --git a/cmd/modInverse.go b/cmd/modInverse.go index aed683c..895863a 100644 --- a/cmd/modInverse.go +++ b/cmd/modInverse.go @@ -48,10 +48,12 @@ func modInverse(cmd *cobra.Command, args []string) { // modInverseCmd represents the modInverse command var modInverseCmd = &cobra.Command{ - Use: "mod-inverse", + Use: "mod-inverse -g N -m N", Short: "Compute a modular inverse", - Long: `Compute a modular inverse.`, - Run: modInverse, + Long: `Compute a modular inverse. + +Given a base g and modulus m, compute a value x such that gx = 1 (mod m). A solution only exists if g and m are coprime.`, + Run: modInverse, } func init() { diff --git a/cmd/partitions.go b/cmd/partitions.go index a45f6fe..edfad54 100644 --- a/cmd/partitions.go +++ b/cmd/partitions.go @@ -89,10 +89,20 @@ func partitions(cmd *cobra.Command, args []string) { // partitionsCmd represents the partitions command var partitionsCmd = &cobra.Command{ - Use: "partitions", + Use: "partitions -n N -k N", Short: "Compute the number of partitions of an integer", - Long: `Compute the number of partitions of an integer.`, - Run: partitions, + Long: `Compute the number of partitions of an integer. + +For example, 4 can be partitioned into +4 +3+1 +2+2 +2+1+1 +1+1+1+1 +so p(n) = 5. + +To compute the number of partitions into at most k parts, provide the -k flag.`, + Run: partitions, } func init() { diff --git a/cmd/pell.go b/cmd/pell.go index 322a223..5734f01 100644 --- a/cmd/pell.go +++ b/cmd/pell.go @@ -60,10 +60,13 @@ func pell(cmd *cobra.Command, args []string) { // pellCmd represents the pell command var pellCmd = &cobra.Command{ - Use: "pell", + Use: "pell -d N", Short: "Find solutions to a Pell equation", - Long: `Find solutions to a Pell equation x^2 - dy^2 = 1.`, - Run: pell, + Long: `Find integer solutions to a Pell equation x^2 - dy^2 = 1. + +This will output solutions infinitely. Try piping to head to only output a certain number of solutions, like this: +mathtools pell -d 12 | head -n 5`, + Run: pell, } func init() { diff --git a/cmd/shoelace.go b/cmd/shoelace.go index 0fc033b..a31add2 100644 --- a/cmd/shoelace.go +++ b/cmd/shoelace.go @@ -99,10 +99,18 @@ func shoelace(cmd *cobra.Command, args []string) { // shoelaceCmd represents the shoelace command var shoelaceCmd = &cobra.Command{ - Use: "shoelace", + Use: "shoelace -f FILE", Short: "Compute the area of a simple polygon from the vertex coordinates", - Long: `Compute the area of a simple polygon from the vertex coordinates.`, - Run: shoelace, + Long: `Compute the area of a simple polygon from the vertex coordinates. + +Put each point on its own line, with each coordinate separated by whitespace. For example, a file with +1 6 +3 1 +7 2 +4 4 +8 5 +will output an area of 16.5.`, + Run: shoelace, } func init() { diff --git a/cmd/sqrtRepetend.go b/cmd/sqrtRepetend.go index a99a676..62c73b3 100644 --- a/cmd/sqrtRepetend.go +++ b/cmd/sqrtRepetend.go @@ -52,10 +52,17 @@ func sqrtRepetend(cmd *cobra.Command, args []string) { // sqrtRepetendCmd represents the sqrtRepetend command var sqrtRepetendCmd = &cobra.Command{ Use: "sqrt-repetend N [N ...]", - Short: "Compute the repetend of the square root of the input", - Long: `Compute the repetend of the square root of the input.`, - Args: cobra.MinimumNArgs(1), - Run: sqrtRepetend, + Short: "Compute the repetend of the continued fraction of square roots", + Long: `Compute the repetend of the continued fraction of the square root of the input. + +For each argument n, this will output the repetend of the continued fraction of sqrt(n). For example, +mathtools sqrt-repetend 12 15 19 +will output +2 6 +1 6 +2 1 3 1 2 8`, + Args: cobra.MinimumNArgs(1), + Run: sqrtRepetend, } func init() { diff --git a/cmd/stirling.go b/cmd/stirling.go index 27eccb8..1a767b9 100644 --- a/cmd/stirling.go +++ b/cmd/stirling.go @@ -58,10 +58,24 @@ func stirling(cmd *cobra.Command, args []string) { // stirlingCmd represents the stirling command var stirlingCmd = &cobra.Command{ - Use: "stirling", + Use: "stirling [-1|-2] -n N -k N", Short: "Compute the Stirling numbers", - Long: `Compute the Stirling numbers.`, - Run: stirling, + Long: `Compute the Stirling numbers. + +The Stirling numbers of the first kind give the coefficients in the expansion of the falling factorial. For example, +x(x-1)(x-2) = x^3 - 3x^2 + 2x +Consequently, s(3,1) = 2, s(3,2) = -3, and s(3,3) = 3. + +The Stirling numbers of the second kind count the number of ways to partition a set of n objects into k non-empty subsets. For example, there are 7 ways to partition a set of 4 objects into 2 non-empty subsets: +{1} {2,3,4} +{2} {1,3,4} +{3} {1,2,4} +{4} {1,2,3} +{1,2} {3,4} +{1,3} {2,4} +{1,4} {2,3} +Therefore S(4,2) = 7.`, + Run: stirling, } func init() { diff --git a/cmd/totient.go b/cmd/totient.go index 5428468..890b164 100644 --- a/cmd/totient.go +++ b/cmd/totient.go @@ -63,10 +63,12 @@ func totient(cmd *cobra.Command, args []string) { // totientCmd represents the totient command var totientCmd = &cobra.Command{ - Use: "totient", + Use: "totient -n N", Short: "Compute the totient function for all numbers less than n", - Long: `Compute the totient function for all numbers less than n.`, - Run: totient, + Long: `Compute the totient function for all numbers less than n. + +The totient function phi(n) counts the numbers up to n that are coprime to n.`, + Run: totient, } func init() {