ACE Stem Tester — Documentation

The Stem Tester is designed to answer questions like:

• What does Form II of root ktb look like in tense 2?
• How does the pattern change when I choose V1 = a, V2 = i?
• How do hollow or defective verbs behave for different pronouns?
• What happens when I attach an object pronoun or genitive pronoun?

It is completely driven by a single core function:

The Stem Tester provides the UI and glue logic around this function: it gathers parameters from the form, loops over pronouns/declensions, calls build_combined_token(), and then converts the result to Arabic, IPA, and translations.

The top panel of ace_stem_tester.php contains the main controls:

• Root (r0, r1, r2) — selected from dropdown (e.g. k, t, b)
• Form — 1–10 (I–X)
• Tense (1–44) — classifications as in docs_tenses.php
• V1 (infl1) — usually the “perfect” internal vowel (a / i / u)
• V2 (infl2) — usually the “imperfect” internal vowel (a / i / u / uw / iy …)
• Conjunction — e.g. wa, fa, etc. (or none)
• Definite Article — al or none
• Subject pronoun:
  • 0 = all 14 pronouns (full conjugation table)
  • 1–14 = a specific pronoun only
• Attached pronoun (object) — e.g. hu, ka, etc.
• Genitive pronoun — used with noun patterns (15–23)
• Declension suffix — for nominal tenses (15–23)
• Particle group (24–44) and member — e.g. lan, lam, laA, etc.
• Assembly mode — Automatic or Manual
• Show spaces — whether to display spaces between conjunction / particles and the verb
• Language — English (Urdu handled in the translation engine if enabled)

When you click Analyze, the Stem Tester runs roughly the following steps:

1. Read input from $_GET or $_POST:
   root (r0,r1,r2), form, tense, infl1, infl2, pronoun index, declension, particle group, etc.
2. Determine the pattern code $F:
   • "1-1" = Form I perfect active
   • "1-2" = Form I imperfect active (yaktubu pattern)
   • "2-7" = Form II passive perfect
   • "8-1" = Form VIII perfect (with assimilation rules)
   • "hol11" / "def22" / "dup1" etc. = special hollow / defective / doubled patterns
3. Loop over pronouns:
   • If pronoun = 0 → loop from 1 to 14
   • Else → use fixed pronoun index
4. Call build_combined_token() for each row:
   list($latinBase, $ipref, $fform, $v1, $v2, $double) = build_combined_token($F, $r0, $r1, $r2, $pronIdx, $infl1, $infl2, $tense);
   This returns the base form (without subject affixes).
5. Add subject prefixes/suffixes:
   • Perfect tense: append suffix from $perfectSuffixes
   • Imperfect tense: add prefix from $imperfectPrefixes and suffix from $imperfectSuffixes
6. Merge conjunction / particle / article / pronouns:
   • Optionally prepend wa, fa, etc.
   • Optionally prepend al (definite article)
   • Append object pronoun (e.g. hu)
   • Append genitive pronoun for nouns (e.g. hi)
7. Convert Latin → Arabic:
   • Using latinToArabic()
   • Inserting sukun between two consonants
   • Inserting shaddah for doubled radicals
   • Applying Tajweed colors (Tafkhīm, Qalqalah, throat letters)
8. Generate IPA using Latin-to-IPA mapping.
9. Generate translation using getTenseTranslation(), based on:
   • Tense (1–44)
   • Voice (active/passive)
   • Pronoun index
   • Form (I–X)
10. Optional: Frequency:
    • If DB is connected, call getQuranMatchCount($latinWord)
    • Display N/A if DB is not available.

The Stem Tester doesn’t hard-code the full stem internally. Instead, it chooses a pattern code $F, which tells build_combined_token() which branch of the big switch to use.

Common categories:

• "1-1" ... "10-1" — Perfect (past) active
• "1-7" ... "10-7" — Perfect (past) passive
• "1-2" ... "10-6" — Imperfect active
• "1-8" ... "10-12" — Imperfect passive-like variants
• "1-13" ... "10-13" — Imperatives and special derived patterns
• "1-14" ... "10-14" — Prohibitives (laA + imperfect)
• "1-15" ... "10-15" — Active participle
• "1-16" ... "10-16" — Passive participle
• "1-17" ... "10-17" — Verbal noun (maṣdar)
• "18-*", "19-*", "20-*", "21-*", "22-*", "23-*" — derived nouns, adjectives, broken plurals
• "mth**" — mithāl (initial weak) verbs
• "hol**" — hollow verbs
• "def**" — defective verbs
• "dup**" — doubled middle radical
• "hmz**" — hamzated roots

The result table has the following columns:

• # — Row index (form-tense-pronoun combination)
• Arabic (colored) — Prefixed + suffixed, colored per Tajweed rules
• Latin (link + freq) — Latin token + optional frequency link
• IPA — Pronunciation
• Translation — English gloss (and Urdu if enabled)

The code such as 1-2-1 can be read as:

• Form: 1 (I)
• Tense: 2 (Active Imperfect)
• Pronoun index: 1 (he)

The Stem Tester is especially useful for testing weak patterns:

• Mithāl (initial weak) → mth** patterns
• Hollow verbs → hol** patterns
• Defective (final weak) → def** patterns
• Doubled radicals → dup** patterns
• Hamzated verbs → hmz** patterns

By changing V1 / V2 and the pronoun, you can see how ACE reshapes the internal vowels.

The Stem Tester also demonstrates tense categories like:

• Subjunctive (lan + imperfect)
• Jussive (lam + imperfect)
• Light / Heavy Emphatic (related to “la” + verb)
• Prohibitive (tense 14, laA + imperfect)

For prohibitive (14), ACE uses dedicated F-codes such as 1-14, 2-14, etc., and for Form VIII, special cases are handled in 8-14 with assimilation.

• Start with a strong verb such as ktb to verify patterns.
• Test first with V1 = a, V2 = u (standard faʿala / yafaʿulu).
• Set pronoun to 0 to see all 14 rows side by side.
• Use a known root + form + tense from the dictionary, then compare Stem Tester output.
• If Arabic or Latin look wrong, check:
  • Did you choose the correct Form?
  • Is the tense appropriate for that Form?
  • Is the verb weak (hollow/defective)? If so, try different F-codes or V1/V2.