/ 
Sim-OPT-0.1018
/ Sim::OPT::Config

NAME

Sim::OPT::Config - optional terminal assistant for creating and editing Sim::OPT configuration files

SYNOPSIS

use Sim::OPT::Config;
Sim::OPT::Config->new(preset => 'esp-r-block')->run;

The module also contains the complete command-line application. If the optional wrapper is installed, use:

simopt-config
simopt-config --preset am-example
simopt-config --load am.pl
simopt-config --list-presets
simopt-config --manual

During development, the module can be run directly:

perl -Ilib lib/Sim/OPT/Config.pm
perl -Ilib lib/Sim/OPT/Config.pm --preset am-example
perl -Ilib lib/Sim/OPT/Config.pm --manual

Or invoke its CLI entry point from any Perl command line where the module is installed:

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

COMMAND-LINE OPTIONS

--preset NAME        start a new configuration from a built-in preset
--list-presets       list built-in presets
--load FILE          load a trusted existing Sim::OPT Perl configuration
--validate FILE      validate a trusted configuration and exit
--check FILE         alias for --validate
--preview            print managed overrides, or the new generated config
--preview-clean      print a clean canonical supported configuration
--save FILE          managed/source-preserving save
--export-clean FILE  write a clean canonical copy
--regenerate         with --save, request clean-export mode
--manual             render this embedded POD manual
--version            print the module version
--help               show concise shell usage

With no non-interactive action, the terminal assistant starts.

INSTALLATION AND SHELL USE

For a normal Sim::OPT installation place this file at:

lib/Sim/OPT/Config.pm

The optional simopt-config executable contains no application logic; it only loads this module and calls Sim::OPT::Config->cli(@ARGV). Installing that small wrapper in a directory on PATH gives the convenient command:

simopt-config

Nothing depends on the wrapper. The module itself remains directly runnable with Perl, which is useful in a source checkout:

perl -Ilib lib/Sim/OPT/Config.pm

To open an existing trusted configuration:

simopt-config problem.pl

or, without the wrapper:

perl -Ilib lib/Sim/OPT/Config.pm problem.pl

To read the complete manual:

simopt-config --manual

or:

perldoc Sim::OPT::Config

PURPOSE

Sim::OPT::Config is an optional authoring and validation layer. It does not replace Sim::OPT configuration files. Its output is a normal Perl configuration file that can be inspected, version-controlled and edited manually.

Version 0.4 is self-contained: the command-line driver, interactive interface, validation, presets, save/export logic, contextual help and complete manual are all contained in this module. It focuses on the following configuration structures:

$mypath
$file
$fileconfig
@sweeps
@varinumbers
@mediumiters / @miditersnum
%dowhat
$simnetwork
$max_processes
@keepcolumns
@weighttransforms
@weights
@weightsaim
$vals{1}{N}{applytype}
$vals{1}{N}{genmodnew}

WORKFLOW

The editor is section-based rather than a mandatory linear wizard. A user may walk through the sections in order when creating a new problem, or jump directly to a section when editing an existing configuration.

Typical workflow:

1. Choose a preset.
2. Set model paths.
3. Define the 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 generated Perl configuration.

PRESETS

Presets provide editable starting states. Version 0.4 includes:

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

New presets are deliberately data-oriented and can be added without changing the menu logic.

LOADING EXISTING CONFIGURATIONS

Existing Perl configurations can be imported. The loader evaluates the file inside a separate package and extracts the supported symbols.

IMPORTANT: a Perl configuration file is executable code. Loading occurs in a separate Perl package, which provides namespace isolation but is not a security sandbox. Only load configuration files from trusted sources.

Version 0.4 preserves imported source. Comments, formatting, unsupported variables, operator-specific parameter blocks and arbitrary custom Perl remain untouched. Changes made through the assistant are represented in a replaceable managed override region. Managed regions include a Managed keys metadata line identifying the settings owned by the assistant. %dowhat changes are emitted key by key rather than by replacing the whole hash. If the effective configuration has not changed, saving preserves the source byte for byte. Existing destinations receive a .bak backup before overwrite.

INITIAL LEVEL SYMBOL

The distributed example uses @mediumiters. Some Sim::OPT material may use @miditersnum. The importer accepts either. When an existing file is loaded, the writer preserves whichever of these two symbols was detected. Presets currently export @mediumiters.

MORPHING OPERATIONS

The interface provides a multi-row guided editor for common four-field applytype records and a raw Perl array-reference escape route. genmodnew has a guided editor for its common seven-part structure: model files, zone/file numbers, constraint files, increments, operation names, reference groups and affected groups. A raw Perl array-reference editor remains available for unusual or expert configurations.

SAVE MODES

Managed update preserves an imported hand-written source and writes only the settings whose effective values differ from the preserved base. Clean export writes a standalone canonical configuration containing the structures understood by this module. Clean export is also available as a preview and does not replace the source being edited in the current session.

An end-of-file managed override cannot retroactively recompute values that the original Perl source derived earlier from a changed setting. Use clean export, or manually place an assignment earlier, when such execution-order dependencies are present.

EXECUTION-ONLY PRESETS

Execution presets can replace only %dowhat, $simnetwork and $max_processes, leaving search topology, paths, objectives and design-variable definitions untouched. This makes presets useful while refining an existing problem rather than only when creating a new one.

VALIDATION

Validation currently checks structural relationships such as:

  • numeric variables used in sweeps have level definitions, while non-numeric Sim::OPT control tokens are preserved;

  • initial levels are within the declared number of levels;

  • block overlap is reported as a warning, not an error;

  • retained-column records have the expected pair structure;

  • @weightsaim has the same length as @weights;

  • common applytype and genmodnew entries are array references.

Validation is intentionally conservative. It cannot prove that an external ESP-r model, constraint script or arbitrary custom Perl expression is semantically valid.

EXTENDING THE MODULE

The recommended extension path is:

1. Add presets before adding new interface branches.
2. Add validation rules for every newly supported configuration relationship.
3. Add guided editors only for stable/common structures.
4. Preserve a raw Perl path for unusual or expert configurations.

DEPENDENCIES

The terminal interface uses Term::ReadKey for single-key menus when it is available and Term::ReadLine for typed answers when available. Either facility may fall back to ordinary line input. Data::Dumper, File::Copy, Getopt::Long and Pod::Text are standard/core Perl facilities in common Perl distributions.

SECURITY

Sim::OPT configuration files are Perl programs. Importing an existing .pl file evaluates it in a separate package in the current Perl process. This isolates the configuration namespace but does not make untrusted Perl safe. Load only trusted local configuration files. The raw-Perl advanced editors have the same requirement.

DEVELOPMENT AND TESTING

A standalone development distribution can use the usual Perl build cycle:

perl Makefile.PL
make
make test
make install

The command-line program does not contain its own application logic. The testable behaviour lives in Sim::OPT::Config, including the cli entry point.

DESIGN PRINCIPLE

The interface is non-mandatory. Sim::OPT remains driven by normal Perl configuration files. The assistant should reduce configuration effort and catch common mistakes without making the user dependent on the assistant or reducing the expressive power of the underlying configuration language.

COPYRIGHT

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