zenith-analyser 1.1.2

A library for analyzing structured temporal laws

zenith_analyser

Zenith Analyser

A powerful Python library for analyzing structured temporal laws with events, chronocoherence, chronodispersal, and hierarchical targets.

Features

• Complete Lexer & Parser: Full Zenith language syntax support
• Temporal Analysis: Analyze laws with events, chronocoherence, and chronodispersal
• Target Hierarchy: Navigate through nested targets with inheritance
• Event Simulation: Simulate event sequences with temporal constraints
• Time Conversion: Convert between Zenith point format (Y.M.D.H.M) and minutes
• AST Manipulation: Parse, analyze, and unparse Zenith code
• Validation: Comprehensive syntax and semantic validation
• Extensible: Easy to extend with custom analyzers

Zenith-Analyser - Complete Documentation

📚 Table of Contents

1. Introduction
2. Core Concepts
3. API Documentation
4. Zenith Point System
5. Zenith Corpora System
6. CLI Usage
7. Zenith Language Specification
8. Advanced Features
9. Examples
10. Installation

---

Introduction

Zenith-Analyser is a comprehensive time management and temporal analysis library that provides tools for modeling, analyzing, and visualizing temporal structures using the Zenith language. It helps users plan, analyze, and optimize their time allocation across various objectives and activities.

Key Features

• Temporal Modeling: Define laws (temporal sessions) and targets (objectives)
• Hierarchical Analysis: Analyze objectives across generations and populations
• Advanced Metrics: Calculate complexity, density, rhythm, and entropy metrics
• Visualization: Generate comprehensive visualizations of temporal data
• CLI Interface: Full command-line interface for analysis workflows

---

Core Concepts

1. Generation & Population

Generation

In Zenith, a generation refers to the hierarchical level of an objective within a goal system. It expresses the structural depth of an objective, from global intentions to concrete and immediate actions. Each objective belongs to a single generation, allowing precise positioning of its role, degree of specialization, and connection with more general or specific objectives.

Population

The population represents the set of active and influential objectives at a given moment. Unlike generation, which is a positional concept, population is a contextual concept. It groups objectives from several generations that interact simultaneously and guide decisions, priorities, and time allocation in lived reality.

Relationship Between Generation and Population

Generation allows understanding where an objective is located, while population allows understanding with which other objectives it acts. An objective can only belong to one generation, but it always participates in a broader population. In Zenith, this distinction enables coherent temporal analysis by separating the structure of objectives from their actual influence on time dynamics.

2. Target (Objective)

Definition

A target is a general or specific objective within a time management project framework. It represents a plannable, hierarchical, and analytically exploitable entity.

Characteristics

1. Key: A unique textual identifier for the target
2. Dictionary: List of specific objectives associated with the target
3. Laws: Planned sessions for working on target objectives
4. Sub-targets: A target can contain other targets for hierarchical structuring

Example

target programming:
    key: "programming"
    dictionnary:
        d1: "Software development expertise."
        d2: "Android and IOS development expertise."
    law Software:
        start_date:1950-01-22 at 12:00
        period:5.15
        Event:
             A[d1]:"Frontend developpement."
             B[d1]:"Backend developpement."
        GROUP:( A 2.15^0 - B|A 1.30^0)
    end_law
    target Mobile:
         key:"Android and IOS developpement expertise."
         dictionnary:
             d1[d2]:"Android developpement."
             d2[d2]:"IOS developpement."
        law android:
            start_date:1950-01-24 at 12:00
            period:9.45
            Event:
                 A[d1]:"Frontend developpement."
                 B[d1]:"Backend developpement."
            GROUP:(A 1.0^1.0 - A|B 2.0^15 - B|A 1.45^0)
        end_law
        law ios:
            start_date:1950-01-25 at 12:00
            period:5.15
            Event:
                 A[d2]:"Frontend developpement."
                 B[d2]:"Backend developpement."
            GROUP:(A 1.0^15 - A 2.0^15 - B 1.45^0)
        end_law
     end_target
end_target

3. Law (Temporal Session)

Definition

A law is a planned session designed to achieve one or more specific objectives of a target. It allows quantifying and structuring time dedicated to each objective.

Characteristics

1. start_date: Date and time when the session begins
2. period: Total planned duration for the session
3. Event: List of actions or learnings, referenced via the target's dictionary
4. GROUP: Notation (A|B subscript^superscript - B subscript^superscript - C subscript^superscript - D|A subscript^superscript ) where:
   • subscript represents chronocoherence duration (useful and directly contributive time)
   • superscript represents chronodispersal duration (used but not directly contributive time)

Example

law a2025_12_25_15_45:
    start_date:2025-12-25 at 15:45
    period:10.0
    Event:
        A: "Learning pandas."
        B:"Sweeping room."
        C:"Preparing of foods."
    GROUP:(A 30^0 - B|C 1.15^0 - C 45^0 - A 15^0 - A|B|C 2.0^0)
end_law

4. Chronocoherence & Chronodispersal

• Chronocoherence: Time that is useful and directly contributive to objectives
• Chronodispersal: Time that is used but not directly contributive to objectives

---

API Documentation

1. LawAnalyser

Role

Manipulates temporal laws — planning structures that define events, their durations (split into chronocoherence for time useful and directly contributive to objectives, and chronodispersal for time used but not directly contributive), and their relationships in a structured temporal framework. In this version, we support two temporal relationships: order (denoted by -), which enforces strict sequential execution where one event fully completes before the next begins (e.g., A - B means A ends before B starts), and simultaneity (denoted by | ), which allows events to occur at the same time without mutual blocking (e.g., (A|B) means A and B run simultaneously, overlapping completely in their active periods). This enables more expressive modeling of parallel or concurrent activities within a single GROUP, while still preserving deterministic validation of overall chronocoherence, dispersal, and total period constraints.

Methods

get_law_names()

Parameters: None Returns: List[str] - names of all defined laws Interpretation: Provides a list of all available temporal programs. Useful for visualizing planning options before deciding which one to use.

analyser = ZenithAnalyser(corpus)
names = analyser.law_analyser.get_law_names()
print(names)
# Returns: ['DailyWork', 'WeeklyPlanning', 'ResearchSessions']

get_law(name)

Parameters: name (str) - law name Returns: dict - complete law structure Interpretation: Allows reading the time exploitation plan in detail before simulation.

law = analyser.law_analyser.get_law("DailyWork")
print(law.keys())
# Keys returned:
# - name: law name
# - date: start date
# - time: start time
# - period: total planned duration
# - dictionnary: internal dictionary of events
# - group: list of events with durations (chronocoherence^chronodispersal)
# - source_node: internal AST representation of the law

# Access events:
for event_name, event_data in law['dictionnary'].items():
    print(event_name, event_data)

validate_law(name)

Parameters: name (str) - law name Returns: List[str] - detected errors (empty if valid) Interpretation: Verifies that the law is temporally coherent.

errors = analyser.law_analyser.validate_law("DailyWork")
if errors:
    print("Errors detected:", errors)
else:
    print("Valid law!")
# Returns: [] or ['Event A overlaps Event B', 'Total period exceeds planned duration']

2. TargetAnalyser

Role

Manages objectives (targets), their hierarchy (generations), and their active context (populations). Allows visualizing how time is invested in different objectives.

Methods

get_targets_by_generation(generation)

Parameters: generation (int) - hierarchical level of objectives Returns: List[dict] - objectives of this generation Interpretation: Isolates objectives at the same level to understand where time is concentrated.

targets_gen1 = analyser.target_analyser.get_targets_by_generation(1)
for t in targets_gen1:
    print(t['name'])

extract_laws_for_target(target_name)

Parameters: target_name (str) - objective name Returns: dict - laws directly and indirectly linked to the objective Interpretation: Shows the temporal field mobilized to achieve an objective.

laws = analyser.target_analyser.extract_laws_for_target("MyTarget")
for law_name, law_data in laws.items():
    print(law_name, law_data['group'])

extract_laws_population(population)

Parameters: population (int) - cumulative depth of generations Returns: dict - set of active laws up to this population Interpretation: Simulates the lived temporal reality where multiple objectives interact.

population_laws = analyser.target_analyser.extract_laws_population(2)
print(list(population_laws.keys()))

3. ZenithAnalyser

Role

Simulates the actual exploitation of time. Combines laws, objectives, and populations to produce concrete readings on temporal coherence, dispersion, and efficiency.

Methods

law_description(name, population=0)

Parameters:

• name (str) - law name
• population (int) - population context

Returns: dict - complete description of the simulated law

desc = analyser.law_description("DailyWork")
print(desc.keys())
# Main dictionary keys:
# - name, start_date, start_time, start_datetime
# - period, period_minutes, end_datetime
# - sum_duration, coherence, dispersal
# - event_count, unique_event_count
# - simulation, event_metrics
# - dispersion_metrics, mean_coherence, mean_dispersal
# - events

# Mini-simulation:
for event in desc['simulation']:
    print(event['event_name'], event['start'], event['end'], event['duration_minutes'])

target_description(target_name)

Parameters: target_name (str) - objective name Returns: dict - complete temporal synthesis of the objective Interpretation: Shows the time actually invested per objective.

target_desc = analyser.target_description("MyTarget")
print(target_desc['events'])

population_description (population=-1)

Parameters: population (int) - population to analyze (-1 = maximum) Returns: dict - complete population simulation Interpretation: Represents cumulative temporal load.

pop = analyser.population_description(population=2)
print(pop['sum_duration'])

period_description(method:str,key:Any,start:str, end:str)

Parameters:

• method (str) - Choose among of law, population or target
• key (int,str or (str, int)) - (int) population to analyze (-1 = maximum) (str) name for target and (str, int) for law it means (str) for name law and (int) for population
• start (str) - str datetime "YYYY-MM-DD at HH:MM"
• end (str) - str datetime "YYYY-MM-DD at HH:MM" Returns: dict - complete population simulation Interpretation: Represents cumulative temporal load.

pop = analyser.period_description(
    method="law",
    key=("daily_work",3),
    start="2026-02-10 at 12:00",
    end="2026-02-15 at 12:00"
)
print(pop['sum_duration'])

analyze_corpus()

Parameters: None Returns: dict - global corpus diagnostic Interpretation: Provides a complete time management dashboard.

corpus = analyser.analyze_corpus()
print(corpus['corpus_statistics'])
# Main keys returned:
# - corpus_statistics, ast_summary, laws, targets, validation

Zenith Point System

Time Conversion Functions

point_to_minutes(point: str) → int

Converts Zenith point notation to total minutes.

Format: years.months.days.hours.minutes (dot-separated) Multipliers: 1 minute = 1 min, 1 hour = 60 min, 1 day = 1440 min (24h), 1 month = 43200 min (30d), 1 year = 518400 min (360d)

point_to_minutes("30")      # → 30 minutes
point_to_minutes("1.0")     # → 60 minutes (1 hour)
point_to_minutes("0.1.30")  # → 90 minutes (1h30)
point_to_minutes("30.0.0")  # → 43200 minutes (30 days)
point_to_minutes("-1.30")   # → -90 minutes

minutes_to_point(total_minutes: int | float) → str

Converts total minutes back to Zenith point notation.

minutes_to_point(30)    # → "30"
minutes_to_point(60)    # → "1.0"
minutes_to_point(90)    # → "0.1.30"
minutes_to_point(150)   # → "0.2.30" (2h30)
minutes_to_point(1440)  # → "1.0.0" (1 day)

Quick Reference

Minutes	Point Format	Meaning
30	"30"	30 minutes
60	"1.0"	1 hour
90	"0.1.30"	1 hour 30 minutes
150	"0.2.30"	2 hours 30 minutes
1440	"1.0.0"	1 day
43200	"30.0.0"	30 days

Common Usage

# Calculate total duration
total = point_to_minutes("2.30") + point_to_minutes("1.15")  # 225 minutes
formatted = minutes_to_point(total)  # "0.3.45" (3h45)

# Convert for display
duration = point_to_minutes("1.45")  # 105 minutes
hours = duration // 60               # 1
minutes = duration % 60              # 45

Zenith Corpora System

Definition

A Zenith Corpora is a structured text file containing temporal data formatted in the Zenith language. These files store time management structures including targets (objectives), laws (temporal sessions), events, and their hierarchical relationships for analysis and planning.

File Specifications

Supported Extensions

Zenith corpus files are identified by three extensions:

• .zenith (primary, recommended format)
• .zth (short form)
• .znth (alternate form)

File Format

Corpora files are plain text with UTF-8 encoding, containing:

• Target definitions with objectives
• Law definitions with time sessions
• Event specifications
• Chronocoherence/dispersal configurations

Example Structure

target Project:
    key: "project_management"
    dictionnary:
        planning: "Project planning phase"

    law WorkSession:
        start_date: 2025-01-15 at 09:00
        period: 2.0
        Event:
            task1[planning]: "Morning review"
        GROUP:(task1 2.0^0)
    end_law
end_target

Loading Corpus Files

load_corpus(path: str) → str

Loads and validates a Zenith corpora file.

from zenith_analyser.utils import load_corpus

# Load corpus file
code = load_corpus("my_project.zenith")  # or .zth, .znth

# Use with analyser
from zenith_analyser.analysers import ZenithAnalyser
analyser = ZenithAnalyser(code)

Requirements:

• File must exist at specified path
• Must have valid extension (.zenith, .zth, or .znth)
• Read as UTF-8 encoded text

Error Cases:

load_corpus("data.txt")      # ❌ Invalid extension
load_corpus("missing.zth")   # ❌ File not found
load_corpus("project.zenith") # ✅ Valid

Usage Example

# Complete workflow
from zenith_analyser.utils import load_corpus
from zenith_analyser.analysers import ZenithAnalyser
from zenith_analyser.metrics import ZenithMetrics

# 1. Load corpus
zenith_code = load_corpus("weekly_schedule.zenith")

# 2. Create analyser
analyser = ZenithAnalyser(zenith_code)

# 3. Generate metrics
metrics = ZenithMetrics(analyser)
simulations = metrics.population_description(1)["simulation"]
results = metrics.get_comprehensive_metrics(simulations)

print(f"Analysis complete: {results['event_count']} events")

Loading and Processing ICS Files with Timezone Normalization

Calendar data is imported from standard iCalendar (.ics) files via the load_ics function, which parses events including their start/end times, summaries (event names), and any present timezone-related information (TZID or VTIMEZONE components). However, timezone information is deliberately ignored: all parsed datetimes — whether they are timezone-aware (with TZID) or floating/naive — are immediately converted to naive datetime objects by removing any tzinfo without performing any offset conversion or normalization to UTC. In other words, the library treats all start and end times exactly as they appear in the ICS file, without adjusting for declared timezones. This means that if events were scheduled in a local timezone (e.g. Africa/Bujumbura, UTC+2), their naive datetime values are kept as-is (local wall-clock time), and no automatic shift to UTC is applied during import. The resulting internal representation is fully naive (tzinfo=None) and reflects the original recorded times without timezone correction. All subsequent calculations in Zenith — durations, chronocoherence, chronodispersal, temporal laws, and simulations — are therefore performed assuming these naive times represent a single, uniform (but unspecified) reference. This simple approach avoids complex timezone handling during parsing, but requires the user to be aware that events from different timezones or with explicit TZID will not be aligned to a common timeline (e.g. UTC) unless manually pre-adjusted before import or post-processed via functions like corpus_timezone or simulations_timezone.

Workflow Example: From ICS Import to Analysis and Export

The typical workflow begins by loading an ICS corpus, computing metrics, running simulations over a long period, exporting the derived temporal laws in native Zenith format (.zth), and finally generating timezone-adjusted ICS-compatible output. Here is an improved and corrected code example:

from zenith_analyser import (
    ZenithMetrics,
    load_ics,
    ZenithAnalyser,
    export_zenith,
    simulations_timezone,
)


corpus = load_ics("corpus.ics")

# Compute basic metrics on the corpus (chronocoherence, dispersal, etc.)
metrics = ZenithMetrics(corpus)

# Initialize analyser and run population-based simulation over a decade
analyser = ZenithAnalyser(corpus)
result = analyser.period_description(
    method="population",
    key=0,
    start="2021-01-06 at 00:00",          # Interpreted as UTC or Internal reference timezone of the corpus
    end="2031-02-15 at 23:45"             # Interpreted as UTC or Internal reference timezone of the corpus
)
simulations = result["simulation"]

# Generate ICS-compatible output with explicit timezone conversion
# (local_tz = display/target timezone; original_tz = reference timezone of input events)
code_law = simulations_ics(simulations=simulations)
with open("corpus.ics", "w", encoding="utf-8") as f:
    f.write(code_law)

# Export the inferred/analyzed temporal laws in native Zenith text format
code_zenith = simulations_timezone(
    simulations=simulations,
    local_tz="UTC",
    original_tz="Africa/Bujumbura"     # e.g., original events were in Bujumbura time (UTC+2)
)
with open("corpus.zenith", "w", encoding="utf-8") as f:
    f.write(code_zenith)
import zenith_analyser as zn

# Load the native Zenith corpus (.zth) — internal dates are in UTC
corpus_ = zn.load_corpus("Corpus_Zenith.zth")

# Create the analyser from the loaded corpus
analyser = zn.ZenithAnalyser(corpus_)

# Convert the entire corpus so that it is expressed in Bujumbura local time
# → all dates/times will be rewritten as if they were in Africa/Bujumbura
code = analyser.corpus_timezone(
    local_tz="Africa/Bujumbura",      # Target timezone (display / wall-clock)
    original_tz="UTC"                 # Internal reference timezone of the corpus
    # or the reverse: local_tz="UTC", original_tz="Africa/Bujumbura"
)

# Save the converted version
with open("Corpus_Zenith_Bujumbura.zth", "w", encoding="utf-8") as f:
    f.write(code)

print("Conversion completed → file 'Corpus_Zenith_Bujumbura.zth' created.")

🛠️ Development Tools

Zenith Time - VS Code Extension

To streamline the creation and editing of .zenith ,.zth et .znthfiles, we've developed a dedicated VS Code extension available on the Visual Studio Code Marketplace.

✨ Key Features

Syntax Highlighting

• Full language support for Zenith Time syntax
• Color-coded elements: targets, laws, events, dictionaries, dates, and operators
• Clear visual distinction between different language constructs

Smart Code Snippets

• target - Complete target block structure with dictionary
• law - Law block with event and group configurations
• event - Quick event declaration
• dict - Dictionary definition template
• mevents - Multiple events with group configuration

Enhanced Productivity

• Automatic bracket/parenthesis/quotes completion
• Code folding for target and law blocks

🚀 Installation

Method 1: VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Zenith Time"
4. Click Install

Method 2: Command Line

code --install-extension zenith-dev.zenith-time

🎯 Usage Examples

The extension automatically activates when you open .zenith, .zth et .znth files. Try these shortcuts:

1. Create a target block: Type target and press Tab
2. Add a law: Type law and press Tab
3. Quick events: Type event or mevents

🛠️ Development Features

• Language Server Protocol ready structure
• Scalable syntax definitions for future language updates
• Cross-platform compatibility (Windows, macOS, Linux)
• Regular updates with new features and improvements

📁 File Support

• .zenith - Primary Zenith Time files
• .znth - Alternative extension
• .zth - Short extension format

The Zenith Time extension significantly improves development workflow by providing intelligent code completion, syntax validation, and visual enhancements specifically tailored for the Zenith Time language ecosystem.

🔗 Integration with Zenith Analyser

The extension works seamlessly with zenith-analyser projects, ensuring consistent syntax highlighting and code structure validation across your development environment.

CLI Usage

Installation

# Installation via pip
pip install zenith-analyser

# Or from source
git clone  https://github.com/frasasu/zenith-analyser
cd zenith-analyser
pip install -e .

Available Commands

zenith analyze - Main Analysis

Analyzes a Zenith corpus and produces a structured report.

Syntaxe :

   zenith analyze <input> [options]

Options :

• -o, --output : Output file (stdout by default)
• --format : output format (json, yaml, text) - default: json
• --law : Analyze a specific law
• --target :Analyze a specific target
• --population : Population level (-1 for maximum)
• --pretty : Pretty-print for JSON

# Basic analysis
zenith analyze corpus.zenith --format json --pretty

# Analyze specific law
zenith analyze corpus.zenith --law "TemporalLaw" --format text

# Analyze from stdin
cat corpus.zenith | zenith analyze -

zenith validate - Syntax Validation

Validates Zenith file syntax.

Syntax :

    zenith validate <input> [options]

Options :

• --strict : treat warnings as errors

# Basic validation
zenith validate corpus.zenith

# Strict validation
zenith validate corpus.zenith --strict

zenith unparse - Code Reconstruction

Converts a JSON AST to Zenith code. Syntax :

    zenith unparse <input> [options]

Options :

• -o, --output :Output file
• --format : Format output code

Examples :

# Reconstruire depuis un AST
zenith unparse ast.json -o reconstructed.zenith

# Avec formatage
zenith unparse ast.json --format
zenith convert - Conversion de format

Converts between different formats.

Syntaxe :

    zenith convert <input> <output> [options]

Options :

• --from : Input format (zenith, json) - default: zenith
• --to :Output format (zenith, json) - default: json

Examples :

# Zenith vers JSON
zenith convert corpus.zenith corpus.json --from zenith --to json

# JSON vers Zenith
zenith convert ast.json reconstructed.zenith --from json --to zenith

zenith metrics - Advanced Metrics

Calculates advanced temporal metrics.

Syntaxe :

    zenith metrics <input> [options]

Options :

• --type : Type of metrics (all, temporal, complexity, density, rhythm, entropy, patterns) - default: all
• -o, --output : Output file
• --format : Output format (json, yaml, text, csv) - default: json
• --law :Analyze a specific law
• --target : Analyze a specific target
• --population : Population level
• --pretty :Pretty-print for JSON

# All metrics
zenith metrics corpus.zenith --type all --format json --pretty

# Temporal metrics in CSV
zenith metrics corpus.zenith --type temporal --format csv -o metrics.csv

# Detailed metrics for a law
zenith metrics corpus.zenith --law "MainSequence" --detailed

zenith visualize - Visualization

Creates visualizations of temporal data.

Syntaxe :

   zenith visualize <input> [options]

Options :

• --type : Visualization type (histogram, pie, scatter, timeline, summary, frequency, all) - default: histogram
• -o, --output : Output file
• --format :Image format (png, jpg, svg, pdf) - default: png
• --law :Visualize a specific law
• --target :Visualize a specific target
• --population :Population level
• --width : Image width in pixels - default: 1200
• --height : Image height in pixels - default: 800
• --title : Custom title

# Duration histogram
zenith visualize corpus.zenith --population 3 --type histogram -o histogram.png

# All visualizations
zenith visualize corpus.zenith --population 3 --type all --output-dir ./visualizations

# Specific timeline
zenith visualize corpus.zenith --law "KeyEvents" --type timeline --title "Chronology"

zenith export - Export complet

Exports data and visualizations to a structured folder.

Syntaxe :

     zenith export <input> [options]

Options :

• -o, --output-dir :Output directory - default: ./zenith_export
• --formats : Formats to export (png, pdf, json, csv) - default: png, json
• --law : Export a specific law
• --target :Export a specific target
• --population : Population level
• --resolution : Image resolution in DPI - default: 300
• --zip : Create a ZIP archive

Exemples :

# Export complet
zenith export corpus.zenith --formats png json csv

# Export spécifique avec ZIP
zenith export corpus.zenith --target "ProjetPrincipal" --formats pdf json --zip

# Export haute résolution
zenith export corpus.zenith --resolution 600

zenith compare - Comparaison multiple

Compare multiple Zenith analyses.

Syntaxe :

     zenith compare <input1> <input2> ... [options]

Options :

• -o, --output :Output file
• --format : Output format (json, text) - default: text
• --labels :Labels for each input
• --population : population level default -1 for max population.
• --visualize :Generate comparison visualizations

Exemples :

# Comparaison basique
zenith compare corpus1.zenith corpus2.zenith corpus3.zenith

# Avec labels personnalisés
zenith compare file1.zenith file2.zenith --labels "VersionA" "VersionB"

# Comparaison avec visualisation
zenith compare corpus_1.zenith corpus_2.zenith --visualize --format json

Complete Analysis Pipeline

# Step 1: Validation
zenith validate my_corpus.zenith --strict

# Step 2: Analysis
zenith analyze my_corpus.zenith --pretty -o analysis.json

# Step 3: Metrics
zenith metrics my_corpus.zenith --population 1 --type all  -o metrics.json

# Step 4: Visualizations
zenith visualize my_corpus.zenith --population 1  --type all --output-dir ./viz

# Step 5: Complete export
zenith export my_corpus.zenith --formats png pdf json --zip

---

Zenith Language Specification

1. General Presentation

Zenith is a specialized language designed to structure and organize temporal textual corpora. It allows modeling temporal laws, events, and their relationships within an organized hierarchy.

2. Basic Structure

Law Example

law LawName:
    start_date: YYYY-MM-DD at HH:MM
    period: number|dotted_number
    Event:
        event1: "description"
        event2: "description"
    GROUP:(event1 5.0^30 - event2 1.20.15^0)
end_law

Target Example

target TargetName:
    key: "main_key"
    dictionnary:
        entry1: "description"
        entry2[index]: "description"
    # Nested blocks (laws or targets) but comments aren't allowed!
end_target

3. Syntax Components

Token Types

• Structural keywords: law, target, end_law, end_target
• Sections: Event, GROUP, start_date, period, key, dictionnary
• Operators: :, ^, -, |,(, ), [, ]
• Data types: identifier, string, date, time, number, dotted_number

AST Structure

corpus_textuel
├── law
│   ├── name
│   └── contents
│       ├── start_date (date + time)
│       ├── period
│       ├── events[]
│       └── group[]
└── target
    ├── name
    └── contents
        ├── key
        ├── dictionnary[]
        └── blocks[]

4. Complete Example

target HistoricalProject:
    key: "industrial_revolution"
    dictionnary:
        innovation: "period of technical innovations"
        social: "major social changes"

    law MainPeriod:
        start_date: 1760-01-01 at 00:00:00
        period: 1.45
        Event:
            steam_engine[innovation]: "invention of the steam engine"
            textile[social]: "textile mechanization"
        GROUP:(steam_engine 30^0 - textile 1.15^0)
    end_law
end_target

---

Advanced Features

1. ZenithMetrics

Advanced statistical analysis, pattern detection, and temporal characterization.

Key Methods:

• calculate_temporal_statistics(): Duration statistics
• calculate_sequence_complexity(): Sequence complexity scoring
• detect_patterns(): Pattern detection using Suffix Array O(n log n)
• calculate_temporal_density(): Event density in time
• calculate_event_frequency(): Event frequency counting

calculate_temporal_statistics()

Calculate temporal statistics of an event sequence.

Paramètres :

• simulations (List[Dict]) :List of event simulations

Retour :

{
    "avg_duration": 45.2,
    "median_duration": 42.5,
    "min_duration": 10.0,
    "max_duration": 120.0,
    "duration_std": 25.3,
    "sum_duration": 904.0,
    "avg_dispersion": 15.8,
    "sum_dispersion": 158.0,
    "events_count": 20
}

Example :

stats = metrics.calculate_temporal_statistics(simulations)
print(f"Durée moyenne: {stats['avg_duration']:.1f} minutes")

calculate_rhythm_metrics()

Analyze the temporal regularity between events.

Paramètres :

• simulations (List[Dict]) : List of event simulations

Retour :

{
    "rhythm_consistency": 0.87,
    "avg_interval": 18.5,
    "interval_std": 5.2,
    "intervals": [15, 20, 16, ...]
}

Consistency index:

• 1.0 : Perfectly regular rhythm
• 0.0 : No discernible rhythm

Complexity Analysis - calculate_sequence_complexity()

Evaluates the complexity of an event sequence.

Paramètres :

• simulations (List[Dict]) : List of event simulations.

Retour :

{
    "complexity_score": 78.5,
    "unique_events_ratio": 0.65,
    "transition_variety": 0.85,
    "unique_transitions_count": 42
}

Score formula :

complexity_score = (unique_ratio * 0.4 + transition_variety * 0.6) * 100

calculate_entropy()

Calculates the information entropy of the sequence.

Paramètres :

• simulations (List[Dict]) : List of event simulations.

Retour : float - Entropy in bits

Exemple :

entropy = metrics.calculate_entropy(simulations)
print(f"Entropie de la séquence: {entropy:.2f} bits")

Pattern Detection- detect_patterns() ⚡ (Optimisé)

Detects recurring patterns in event sequences.

Algorithm: Suffix Array + LCP in O(n log n)

Paramètres :

• simulations (List[Dict]) :List of event simulations.
• min_pattern_length (int, optionnel) : Minimum pattern length (default: 2)

Retour :

[
    {
        "pattern": ["eventA", "eventB", "eventC"],
        "occurrences": [(0, 3), (15, 18), (42, 45)],
        "length": 3
    },
]

Usage Example :

patterns = metrics.detect_patterns(simulations, min_pattern_length=3)
for pattern in patterns:
    print(f"Motif '{' -> '.join(pattern['pattern'])}' trouvé {len(pattern['occurrences'])} fois")

Temporal Density - calculate_temporal_density()

It calculates the density of events over time.

Paramètres :

• simulations (List[Dict]) : List of Simulations

Retour :

{
    "temporal_density": 0.75,
    "coverage_ratio": 75.0,
    "total_simulation_time": 1200,
    "effective_event_time": 900
}

Formule : temporal_density = effective_event_time / total_simulation_time

Event Frequencies- calculate_event_frequency()

It counts the frequency of each type of event.

Arguments :

• simulations (List[Dict]) : List of Simulations Retour :

Dict[str, int] - Dictionary {event_name: frequency}

Example :

freq = metrics.calculate_event_frequency(simulations)
for event, count in sorted(freq.items(), key=lambda x: x[1], reverse=True):
    print(f"{event}: {count} occurrences")

Example:

from zenith_analyser.metrics import ZenithMetrics

metrics = ZenithMetrics(code_zenith)
simulations = metrics.law_description("TemporalLaw", population=3)["simulation"]
comprehensive = metrics.get_comprehensive_metrics(simulations)

print(f"Complexity Score: {comprehensive['sequence_complexity']['complexity_score']:.1f}")
print(f"Temporal Density: {comprehensive['temporal_density']['temporal_density']:.2f}")

2. ZenithVisualizer

Comprehensive visualization of temporal data.

Key Methods:

• plot_duration_histogram(): Duration distribution
• plot_event_pie_chart(): Event proportion
• plot_sequence_scatter(): Temporal sequence scatter plot
• plot_timeline(): Event timeline
• create_all_plots(): Generate all visualizations at once

Example:

from zenith_analyser.visuals import ZenithVisualizer

visualizer = ZenithVisualizer(metrics)

# Generate all plots
files = visualizer.create_all_plots(
    simulations,
    metrics_data=metrics_data,
    prefix="analysis_law",
    output_dir="./visualizations"
)

Important: Current Design – Unitary Corpora & Single Time Manager (v1.1.0)

zenith-analyser is intentionally designed around a unitary corpus model:

• One corpora = one time manager
  Each .zenith file represents a single agent or single decision-making entity (a person, a role, or an organization treated as one unified actor).

• Sequential only – no native parallelism
  Events within a GROUP are executed in strict sequence (using the - operator).
  There is no built-in support for concurrent / simultaneous tasks (no parallel execution, no multi-threading syntax like | or concurrent blocks).

This design choice keeps the language simple, simulations deterministic, and analyses coherent and predictable.

What this means in practice

• Perfect for:

  • Individual productivity tracking (freelancers, students, personal goals)
  • Single-role or unified-entity modeling (e.g., "the company" as one time allocator)
  • Deep, focused analysis of one person's/ entity's time allocation

• Not (yet) supported:

  • Multiple independent agents interacting in the same file
  • True parallel tasks (e.g., coding while attending a meeting)
  • Multi-user / team simulations in a single corpus

How to handle multiple units / people / teams

Simply create one .zenith file per unit:

• alice.zenith → Alice's personal time laws
• bob.zenith → Bob's personal time laws
• team-lead.zenith → Team leader's overview

Then use the built-in CLI to compare or aggregate insights:

zenith compare alice.zenith bob.zenith --population 1 --labels "Version 1.0" "Version 2.0" --format json -o comparisons/v1_v2.json
zenith metrics alice.zenith --type all

---

Examples

Example 1: Complete Historical Analysis

# 1. Complete corpus analysis (JSON format)
zenith analyze data/corpus.zenith --format json --pretty -o outputs/analyse_brute.json

# 2. Analysis in readable text format
zenith analyze data/corpus.zenith --population 1 --format text -o outputs/analyse_lisible.txt

# 3. Analysis in YAML format (if pyyaml is installed)
zenith analyze data/corpus.zenith --population 1 --format yaml -o outputs/analyse.yaml

# 4. Analysis of a specific law
zenith analyze data/corpus.zenith --law "session_matin" --format json -o outputs/loi_session_matin.json

# 5. Analysis of a specific target
zenith analyze data/corpus.zenith --target "projet_web" -o outputs/cible_projet_web.json

# 6. Analysis by population level
zenith analyze data/corpus.zenith --population 2 -o outputs/population_niveau2.json

# 7. Analysis from stdin via pipe
cat data/corpus.zenith | zenith analyze - --format json | ConvertFrom-Json | Select-Object -ExpandProperty corpus_statistics | ConvertTo-Json

# 8. All corpus metrics
zenith metrics data/corpus.zenith --population 2 --type all --format json --pretty -o metrics/toutes_metriques.json

# 9. Temporal metrics in CSV format
zenith metrics data/corpus.zenith --population 2 --type temporal --format csv -o metrics/metriques_temporelles.csv

# 10. Complexity metrics
zenith metrics data/corpus.zenith --population 2 --type complexity --detailed -o metrics/complexite_detaillee.json

# 11. Density metrics
zenith metrics data/corpus.zenith --population 2  --type density --format json -o metrics/densite.json

# 12. Rhythm metrics
zenith metrics data/corpus.zenith --population 2 --type rhythm -o metrics/rythme.json

# 13. Entropy metrics
zenith metrics data/corpus.zenith --population 2  --type entropy --format yaml -o metrics/entropie.yml

# 14. Pattern detection
zenith metrics data/corpus.zenith --population 2  --type patterns --format json --pretty -o metrics/motifs.json

# 15. Metrics for a specific population
zenith metrics data/corpus.zenith  --population 3 --type all -o metrics/population3_metriques.json

# 16. Metrics for a specific law
zenith metrics data/corpus.zenith --law "reunion_equipe" --type all -o metrics/loi_reunion.json

# 17. Duration histogram
zenith visualize data/corpus.zenith --target "developpement" --type histogram --width 1600 --height 900 -o visualizations/histogramme_durees.png --title "Distribution des Durées"

# 18. Event timeline
zenith visualize data/corpus.zenith --type timeline --population 2 -o visualizations/timeline_population2.svg --format svg

# 19. Event pie chart
zenith visualize data/corpus.zenith --type pie --target "zenith" -o visualizations/repartition_sante.pdf --format pdf

# 20. Sequence scatter plot
zenith visualize data/corpus.zenith --type scatter --law "sprint_1"  -o visualizations/scatter_sprint1.jpg

# 21. Metrics summary
zenith visualize data/corpus.zenith --type summary --population 1 -o visualizations/resume_metriques.png

# 22. Event frequency
zenith visualize data/corpus.zenith --type frequency --law "sprint_1" -o visualizations/frequence_evenements.png

# 23. All visualizations at once
zenith visualize data/corpus.zenith --population 1 --type all  --width 1400 --height 800 --title "Analyse Complète du Corpus"

# 24. Complete export (data + visuals)
zenith export data/corpus.zenith --population 1 --output-dir exports/complete --formats png json csv --resolution 300 --zip

# 25. Target-specific export
zenith export data/corpus.zenith --target "developpement" --output-dir exports/developpement --formats pdf json --zip

# 26. Zenith → JSON conversion
zenith convert data/corpus.zenith exports/corpus.json --from zenith --to json

# 27. JSON → Zenith conversion
zenith convert exports/ast.json exports/reconstructed.zenith --from json --to zenith

# 28. Unparse from AST
zenith unparse data/ast_template.json -o exports/code_regenere.zenith --format

# 29. Comparison of two corpora
zenith compare data/corpusv1.zenith data/corpusv2.zenith --labels "Version 1.0" "Version 2.0" --format json -o comparisons/v1_v2.json

# 30. Population comparison
zenith compare data/corpus.zenith data/corpus_optimise.zenith --population 2  --format text --output comparisons/populations_diff.txt

# 31. Automated analysis pipeline
zenith validate data/corpus.zenith --strict 
zenith analyze data/corpus.zenith --population 1 --pretty > analysis/full_analysis.json 
zenith metrics data/corpus.zenith  --population 1 --type all > analysis/metrics.json 
zenith export data/corpus.zenith --population 1 --output-dir analysis/export --zip

Example 2: Python Integration

import subprocess
import json

# Execute zenith from Python
result = subprocess.run(
    ["zenith", "analyze", "corpus.zenith", "--format", "json"],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)

# Process the data
print(f"Total events: {data['corpus_statistics']['total_events']}")
print(f"Total duration: {data['corpus_statistics']['total_duration_minutes']} minutes")

Example 3: Example analysis with metrics

import json
from zenith_analyser.metrics import ZenithMetrics
from zenith_analyser.utils import load_corpus

corpus = load_corpus("Corpus_Zenith.zth")
metrics = ZenithMetrics(corpus)

simulations = metrics.target_description("maitrise_soi")["simulation"]
statistics = metrics.calculate_temporal_statistics(simulations)
print(json.dumps(statistics, indent=4))

# event frequency
frequencies = metrics.calculate_event_frequency(simulations)
print(json.dumps(frequencies, indent=4))

# sequence complexity
sequences = metrics.calculate_sequence_complexity(simulations)
print(json.dumps(sequences, indent=4))

#temporal density

temporal = metrics.calculate_temporal_density(simulations)
print(json.dumps(temporal, indent=4))

# rhythms
rhythms = metrics.calculate_rhythm_metrics(simulations)
print(json.dumps(rhythms, indent=4))

# patterns
patterns = metrics.detect_patterns(simulations)
print(json.dumps(patterns, indent=4))

# entropy
entropy = metrics.calculate_entropy(simulations)
print(json.dumps(entropy, indent=4))

# all metrics for target
metrics_target = metrics.get_metrics_target("maitrise_soi")
print(json.dumps(metrics_target, indent=4))

# all metrics for population
metrics_population = metrics.get_metrics_population(3)
print(json.dumps(metrics_population, indent=4))

#  all metrics for law
metrics_law = metrics.get_metrics_law("a2026_01_04_05_15",5)
print(json.dumps(metrics_law, indent=4))

# get data with pandas
data_target = metrics.get_data_population(3)
print(data_target)

Example 4: Example analysis with visualisations

from zenith_analyser.metrics import ZenithMetrics
from zenith_analyser.visuals import ZenithVisualizer,create_simple_plot
from zenith_analyser.utils import load_corpus

corpus = load_corpus("Corpus_Zenith.zth")
metrics = ZenithMetrics(corpus)
visual = ZenithVisualizer(metrics)

#plot duration histogram
simulations = metrics.target_description("vie_equilibre")["simulation"]
visual.plot_duration_histogram(simulations=simulations,title="Duration histogram") # you can save path

# plot  event_pie chart
visual.plot_event_pie_chart(simulations=simulations, title="Event pie chart.")

# plot sequence sactter
visual.plot_sequence_scatter(simulations=simulations)

# plot timeline
simu = metrics.target_description("developpement")["simulation"]
visual.plot_timeline(simulations=simu)


#plot metrics summary
metrics_ = metrics.get_metrics_target("vie_equilibre")
visual.plot_metrics_summary(metrics_)

#plot event frequency
visual.plot_event_frequency(simulations=simulations)

#create all plots
visual.create_all_plots(simulations=simulations, metrics_data=metrics_)

#comparison
simulations_1 = metrics.target_description("maitrise_soi")['simulation']
simulations_2 = metrics.target_description("developpement")['simulation']

visual.plot_simple_comparison(simulations_list=[simulations_1,simulations_2], labels=["maitrise_soi","developpement"])

#simple plot
data = metrics.get_data_target("vie_equilibre")
create_simple_plot(data=data["coherence"],plot_type="line")
create_simple_plot(data=data["coherence"],plot_type="bar")
create_simple_plot(data=data["coherence"],plot_type="scatter")

---

Installation

Basic Installation

pip install zenith-analyser

Development Installation

git clone https://github.com/frasasu/zenith-analyser.git
cd zenith-analyser
pip install -e ".[dev]"

---

Conclusion

Zenith-Analyser provides a comprehensive framework for temporal management and analysis. By distinguishing between generations (structural hierarchy) and populations (contextual activity), it offers unique insights into time allocation and objective management.

Key Benefits:

1. Structural Clarity: Clear separation between objective hierarchy and active context
2. Temporal Precision: Accurate modeling of time allocation with chronocoherence/dispersal
3. Analytical Depth: Advanced metrics for complexity, rhythm, and pattern analysis
4. Visual Insight: Comprehensive visualization of temporal structures
5. Workflow Integration: Full CLI and Python API for seamless integration

Use Cases:

• Personal Time Management: Plan and analyze daily/weekly activities
• Project Management: Structure objectives and track temporal investment
• Research Analysis: Model historical or sequential processes
• Process Optimization: Identify temporal patterns and inefficiencies

For more information, examples, and contributions, visit the GitHub repository.