/ 
Sim-OPT-0.1018
/ Sim::OPT::ConfigEditor

NAME

Sim::OPT::ConfigEditor - optional interactive editor and authoring assistant for Sim::OPT Perl configuration files

VERSION

Version 0.04.

PURPOSE

Sim::OPT::ConfigEditor is an optional terminal assistant for creating, inspecting, validating and editing ordinary Sim::OPT Perl configuration files. It does not replace the Perl configuration format and it is not required to run Sim::OPT. The module contains its presets, interface, validation logic, context-sensitive help, command-line interface and this complete manual in one .pm file.

The guiding principle is that the assistant should expose Sim::OPT concepts without imprisoning expert users in the interface. Presets and questions help beginners; ordinary Perl remains the runtime truth and the advanced escape route.

SHELL USE

The module is deliberately dual-use: it can be loaded as a normal Perl module or executed directly as a command-line program.

From a source tree:

perl lib/Sim/OPT/ConfigEditor.pm

Show the manual:

perl lib/Sim/OPT/ConfigEditor.pm --manual

List presets:

perl lib/Sim/OPT/ConfigEditor.pm --preset-list

Start from a preset:

perl lib/Sim/OPT/ConfigEditor.pm --preset am-example

Edit an existing trusted configuration:

perl lib/Sim/OPT/ConfigEditor.pm /path/to/problem.pl

Validate without opening the interface:

perl lib/Sim/OPT/ConfigEditor.pm --check /path/to/problem.pl

Preview the managed override block:

perl lib/Sim/OPT/ConfigEditor.pm --preview /path/to/problem.pl

Preview a standalone canonical configuration:

perl lib/Sim/OPT/ConfigEditor.pm --preview-clean /path/to/problem.pl

Export a standalone canonical configuration:

perl lib/Sim/OPT/ConfigEditor.pm --export-clean clean.pl /path/to/problem.pl

Show the version:

perl lib/Sim/OPT/ConfigEditor.pm --version

If the file has executable permission, its shebang also allows:

./lib/Sim/OPT/ConfigEditor.pm --manual

If an optional simopt-config wrapper is installed, all the same arguments can be used more conveniently:

simopt-config
simopt-config --preset am-example
simopt-config problem.pl

A wrapper is only an alias. It is not required; all functionality is in this module.

When the module is installed in Perl's module path and no wrapper is available, it can also be invoked with:

perl -MSim::OPT::ConfigEditor -e 'exit Sim::OPT::ConfigEditor->cli(@ARGV)' -- --manual

PERL API

Normal module use does not launch the interface:

use Sim::OPT::ConfigEditor;

my $editor = Sim::OPT::ConfigEditor->new(preset => 'esp-r-block');
$editor->run_interactive;

The command-line dispatcher can also be called explicitly:

exit Sim::OPT::ConfigEditor->cli(@ARGV);

Executing the .pm file directly calls the same cli method. Loading it with use or require does not.

QUICK START

For a new problem the typical workflow is:

  1. Choose a preset.

  2. Set project/model paths.

  3. Define search blocks in @sweeps.

  4. Set variable levels and initial levels.

  5. Review %dowhat and simulation options.

  6. Define retained result columns and objective construction.

  7. Add common morphing definitions.

  8. Validate.

  9. Preview and save the resulting ordinary Perl configuration.

The interface is section-based rather than a mandatory linear wizard. A user may walk through these sections in order or jump directly to any section.

NAVIGATION

The main interface is divided into Project, Search, Execution, Objectives and Design variables. Every section has local help.

If Term::ReadKey is available, menu choices are single-key. If it is not available, the editor falls back to ordinary line input and ENTER. Free-form values always use line input. Empty input normally keeps the current value. b returns to the previous menu where offered.

The interface is intentionally non-mandatory. A generated or edited configuration remains an ordinary readable .pl file and can always be edited by hand.

SUPPORTED CONFIGURATION STRUCTURES

Version 0.04 deliberately concentrates on the skeleton of a Sim::OPT problem.

Project and files

  • $mypath

    Working directory used by the Sim::OPT problem.

  • $file

    Root model/directory name (a historical Sim::OPT name).

  • $fileconfig

    Main model configuration file, normally found below cfg/.

Search structure

  • @sweeps

    Declares search plans and blocks. A top-level item is a search plan; each plan contains blocks; each block contains variable numbers or advanced Sim::OPT control tokens. Tokens such as 2>1 are preserved as strings rather than reinterpreted by the assistant.

  • @varinumbers

    Declares the number of discrete levels/iterations available to each design variable.

  • @mediumiters / @miditersnum

    Declares the base or starting level of each variable. The importer accepts both spellings. Internally the editor uses one initial-level concept and remembers the spelling detected in an existing source file. Presets currently export the canonical @mediumiters spelling.

Execution

  • %dowhat

    Controls active Sim::OPT stages and several search/simulation options. Presets supply common starting combinations; scalar entries can then be edited individually. Structured values are preserved and displayed.

  • $simnetwork

    Declares whether the simulation model uses a mass/flow network.

  • $max_processes

    Maximum number of processes used by the configured workflow.

Results and objectives

  • @keepcolumns

    Selects named columns from result tables.

  • @weighttransforms

    Combines or transforms retained values into derived objectives. Perl expressions are preserved as strings.

  • @weights

    Assigns numeric weights to objective terms.

  • @weightsaim

    Declares the numeric aim/direction associated with the weighted objectives.

Design variables

  • $vals{1}{N}{applytype}

    Describes how variable N applies a model change. The common representation is a list of rows containing operator type, source file, target file and zone/context identifier. The editor provides a guided row editor and an advanced raw-Perl ARRAY-reference path.

  • $vals{1}{N}{genmodnew}

    Describes general model changes and optional constraint propagation. The common seven-part structure contains model/geometry files, zone/file numbers, constraint files, increments, operation names, reference groups, and affected entity groups. A guided editor is provided for this common structure, while a raw Perl ARRAY-reference editor remains available for unusual expert cases.

PRESETS

Presets merely populate ordinary Sim::OPT variables. They do not introduce a new runtime format. Version 0.04 includes:

esp-r-standard
esp-r-block
esp-r-single
esp-r-star
morph-only
precomputed-search
precomputed
minimal
am-example

Preset definitions are data-oriented so additional presets can be added without redesigning the menu logic.

LOADING EXISTING CONFIGURATIONS

A Sim::OPT configuration is a Perl program. Importing a configuration executes its Perl code inside a separate package and copies the supported symbols into the editor's internal representation.

Only load trusted local configuration files. Package isolation avoids namespace pollution; it does not turn untrusted Perl code into safe data.

Unknown or unsupported Perl remains in the preserved source when managed-update mode is used.

ROUND-TRIP / MANAGED SAVE

Managed-update mode preserves the original source and appends or replaces one clearly marked override block. The block is computed from semantic differences between the current supported configuration and the preserved source baseline. It does not depend on which menu changed the value.

Consequently:

  • programmatic changes are detected;

  • changing a value and then restoring its original value removes its override;

  • %dowhat differences can be represented key by key;

  • comments, formatting, examples, unsupported settings and custom Perl remain untouched;

  • a true no-op save can preserve an imported file byte-for-byte;

  • existing destinations receive a .bak backup before overwrite.

The managed region is replaceable rather than cumulative, so repeated saves do not keep appending duplicate override blocks.

Important Perl-order limitation

An assignment appended at the end of a Perl configuration cannot retroactively recompute a value that the original source derived earlier from the old setting. If an existing configuration contains such dependencies, use clean export or manually place the relevant assignment before the dependent code.

CLEAN EXPORT

Clean export writes a standalone canonical Sim::OPT .pl containing the settings understood by ConfigEditor. It is particularly useful for new configurations and for eliminating possible end-of-file dependency issues.

Unsupported custom Perl from an imported file is not copied into a clean export. Managed update and clean export therefore serve different purposes; neither replaces the other.

RAW ADVANCED EDITING

The common applytype and genmodnew forms have guided editors. Both retain an expert raw-Perl escape hatch. Raw replacements must evaluate to ARRAY references where the corresponding Sim::OPT structure requires one.

Raw input is evaluated locally. Use this facility only with code you trust and understand.

VALIDATION

Validation is intentionally conservative. It checks structural relationships that can be established without pretending to prove arbitrary Sim::OPT or ESP-r semantics.

Current checks include:

  • malformed or empty sweep blocks;

  • numeric sweep variables missing level definitions;

  • invalid numbers of levels;

  • initial levels outside their declared ranges;

  • overlapping blocks, reported as warnings rather than errors;

  • malformed @keepcolumns records;

  • numeric @weights and @weightsaim entries;

  • objective list-length relationships where they can be inferred;

  • common applytype shapes;

  • common operator/parameter-block relationships, including mappings such as rotation to rotate, translation to translate, surface_rotation to rotate_surface, thickness_change to change_thickness, and obs_modification to obs_modify.

Warnings are advisory. Expert configurations may intentionally use structures beyond the subset currently understood by the editor.

CONTEXT-SENSITIVE HELP

Help for individual sections is embedded in the module as structured text and is available from the interactive menus. The full manual is this POD document. The --manual command renders this POD at runtime, so the command-line manual and the module documentation have one source of truth.

You can also read the same manual with standard Perl tools:

perldoc Sim::OPT::ConfigEditor

or directly from the file:

perldoc lib/Sim/OPT/ConfigEditor.pm

COMMAND-LINE OPTIONS

--preset NAME

Start a new configuration from the named built-in preset.

--preset-list

List available presets.

--check

Load and validate the supplied configuration, then exit. Validation errors produce a non-zero status.

--preview

Print the managed override block that would be required for the current configuration.

--preview-clean

Print a standalone canonical configuration.

--export-clean FILE

Write a standalone canonical configuration to FILE.

--manual

Render and print this embedded POD manual.

--version

Print the module version.

--help

Print concise command-line usage.

DEPENDENCIES

The implementation uses standard/core Perl facilities where practical. Term::ReadKey is optional; when unavailable the interface falls back to line-oriented menu input. The embedded manual is rendered with Pod::Text.

EXTENDING THE EDITOR

The recommended development strategy is:

  1. Add data-oriented presets before adding new interface branches where a preset can express the required variation.

  2. Add validation rules for every newly supported configuration relationship.

  3. Add guided editors only for stable/common structures.

  4. Always preserve a raw-Perl path for unusual or expert configurations.

Natural next targets include operator-specific editors for translate, rotate, obs_modify and change_climate; retrieval/reporting wizards; additional %dowhat schemas; and user-defined preset directories.

DISTRIBUTION

The .pm file is sufficient for the configuration assistant itself. A bin/simopt-config program, if supplied by a Sim::OPT distribution, can be a minimal convenience wrapper containing only:

#!/usr/bin/env perl
use Sim::OPT::ConfigEditor;
exit Sim::OPT::ConfigEditor->cli(@ARGV);

Such a wrapper contains no functionality or documentation that is absent from the module.

SECURITY

Sim::OPT configuration files and the advanced raw editors evaluate Perl code. Only load or enter code from trusted sources.

AUTHOR

# Copyright (C) 2008-2026 by Gian Luca Brunetti, gianluca.brunetti@gmail.com.