Merge branch 'master' into dependabot/npm_and_yarn/gui-js/axios-1.8.2

Author: highperformancecoder

Makefile

@@ -187,7 +187,7 @@ EXES=gui-tk/minsky$(EXE)
 endif
 
 
-DYLIBS=libminsky.$(DL) libminskyEngine.$(DL) libcivita.$(DL)
+DYLIBS=libminsky.$(DL) libminskyEngine.$(DL) libcivita.$(DL) 
 MINSKYLIBS=-lminsky -lminskyEngine -lcivita
 
 
@@ -272,6 +272,9 @@ ifdef MXE
 BOOST_EXT=-mt-x64
 EXE=.exe
 DL=dll
+FLAGS+=-DMXE
+PYMINSKY=gui-js/dynamic_libraries/pyminsky.pyd
+PYTHONCAPI=ecolab/classdesc/pythonCAPI.o # extra python.lib shims required on Windows
 FLAGS+=-D_WIN32 -DUSE_UNROLLED -Wa,-mbig-obj
 # DLLS that need to be copied into the binary directory
 MXE_DLLS=libboost_filesystem-mt-x64 libboost_thread-mt-x64 \
@@ -288,6 +291,7 @@ DLLS=$(wildcard $(MXE_DLLS:%=$(BINDIR)/%*.dll))
 else
 EXE=
 DL=so
+PYMINSKY=pyminsky.so
 BOOST_EXT=
 # try to autonomously figure out which boost extension we should be using
   ifeq ($(shell if $(CPLUSPLUS) test/testmain.cc $(LIBS) -lboost_system>&/dev/null; then echo 1; else echo 0; fi),0)
@@ -328,9 +332,10 @@ GUI_LIBS=
 FLAGS+=-DBOOST_SIGNALS_NO_DEPRECATION_WARNING
 
 # add the python module build here
+EXES+=$(PYMINSKY)
 ifeq ($(OS),Linux)
 ifndef MXE
-EXES+=pyminsky.so createLinkGroupIcons
+EXES+=createLinkGroupIcons
 endif
 endif
 
@@ -445,8 +450,13 @@ endif
 libminsky.a: $(RESTSERVICE_OBJS) $(MODEL_OBJS) $(SCHEMA_OBJS) $(ENGINE_OBJS)
 	ar r $@ $^
 
-pyminsky.so: pyminsky.o libminsky.a
+$(PYMINSKY): pyminsky.o $(PYTHONCAPI) libminsky.a
+ifeq ($(OS),Darwin)
+	c++ -bundle -undefined dynamic_lookup -Wl,-no_pie -Wl,-search_paths_first -mmacosx-version-min=$(MACOSX_MIN_VERSION) -arch $(ARCH) -stdlib=libc++  -o $@  $^ $(LIBS)
+	cp pyminsky.so gui-js/build/
+else
 	$(LINK) -shared -o $@ $^ libminsky.a $(LIBS)
+endif
 
 # used to find undefined symbols in pyminsky.so
 pyminsky-test: test/testmain.o pyminsky.o libminsky.a
@@ -489,7 +499,8 @@ clean:
 mac-dist:
 # force rebuild of the node file to force rewriting of dependent dylibs
 	rm -rf gui-js/build
-	$(MAKE) gui-js/build/minskyRESTService.node
+	$(MAKE) gui-js/build/minskyRESTService.node pyminsky.so
+	cp pyminsky.so gui-js/build
 # create executable in the app package directory. Make it 32 bit only
 #	mkdir -p minsky.app/Contents/MacOS
 #	sh -v mkMacDist.sh

Readme.md

@@ -14,6 +14,11 @@ Minsky is an open source program with prebuilt binaries available for:
 - [Mac OS X](https://sourceforge.net/projects/minsky/files/Mac%20Binaries/)
 - [various Linux distributions](https://build.opensuse.org/package/show/home:hpcoder1/minsky)
 
+## Using Minsky in "batch mode" from Python
+A little known secret is that Minsky can be used in a headless batch mode, a capability it has had from the beginning in the form of TCL scripting. Since March 2024, Python scripting has been available in Linux builds, and is coming soon to Windows and Mac builds (version 3.12). TCL scripting is deprecated and will soon be removed from the codebase.
+
+[Introduction to scripting Minsky in Python](python-minsky.md)
+
 ## Compiling Minsky from source code
 
 Official releases are available from [SourceForge](https://sourceforge.net/projects/minsky/files/Sources/). You may also obtain later releases from this Github project, as release are tagged within git.

ecolab

@@ -44,7 +44,9 @@ rewrite_dylib()
 {
     local dylib=$1
     local target=$2
-    cp -f $dylib $MAC_DIST_DIR
+    if [ ! -x $MAC_DIST_DIR/${dylib##*/} ]; then
+        cp -f $dylib $MAC_DIST_DIR
+    fi
     chmod u+rw $MAC_DIST_DIR/${dylib##*/}
     rewrite_dylibs $MAC_DIST_DIR/${dylib##*/}
     echo "install_name_tool -change $dylib @loader_path/${dylib##*/} $target"
@@ -75,6 +77,7 @@ rm -rf $MAC_DIST_DIR/*.dylib
 mkdir -p $MAC_DIST_DIR
 
 rewrite_dylibs $MAC_DIST_DIR/minskyRESTService.node
+rewrite_dylibs $MAC_DIST_DIR/pyminsky.so
 
 pushd gui-js
 # libravel.so expects certain dylibs in node-addons for legacy

mkMacRESTService.sh

@@ -0,0 +1,71 @@
+# Scripting Minsky in Python
+There are a number of applications for driving Minsky from scripts, ranging from automating tasks over multiple .mky files, regression tests, parameter sweeps and ensemble runs. Since early 2024. it has been possible to script Minsky using Python. Note Python 2 is _not_ supported, you must use Python 3.x
+
+## Setting the python path to find the pyminsky module
+
+- On *Linux*, this step is unnecessary if you have installed Minsky from the Open Build Service, as the pyminsky module is installed in a standard location for the standard python or python3 executable for that distro. If you are using a non-standard python version, you will need to copy or link the module (pyminsky.so) to somewhere in your python path.
+- On *Windows*, the python module (pyminsky.pyd) is installed in the same directory as Ravel executable. On my system that is $LOCALAPPDATA/Programs/minsky. So the following snippet should set up you python path:
+  ~~~~
+  import sys,os
+  sys.path.append(os.environ['LOCALAPPDATA']+'\\Programs\\minsky')
+  ~~~~
+- On *MacOS*, the python module (pyminsky.so) is located in the Resource directory of whereever you have installed ravel.app. Assuming you have installed this in the standard location, the following snippet should work
+  ~~~~
+  import sys,os
+  sys.path.append('/Applications/ravel.app/Contents/Resources/build')
+  ~~~~
+
+## The minsky object
+Minsky is structured around a singleton object "minsky". So pyminsky has a minsky object that refers to the C++ Minsky singleton. An example usage is:
+ ~~~~
+from pyminsky import minsky
+print(minsky.minskyVersion())
+print(minsky.t())   # print the current timestep
+minsky.t(10.2)      # set the timestep to 10.2
+~~~~
+
+## C++ reflection
+The pyminsky module reflects the C++ code. Pretty much all public methods and attributes of the C++ classes are accessible from Python. 
+
+### Attributes
+Attributes appear as an overloaded _getter/setter_ pair. Calling the attribute without an argument is treated as a getter, and with an argument as a setter. C++ `bool`, numeric and string types map to the obvious Python equivalents. Standard vectors, lists and sets map to python lists. Standard maps map to a list first/second pairs containing the key-value pairs. Structs and classes are mapped to dicts.
+
+Compound types have additional syntax elements. You can access the individual methods and attributes of a class or struct member, eg
+~~~~
+>>> minsky.model.items()
+[{'bb': {}, 'bookmark': False, 'deleteCallback': '', 'm_sf': 1.0, 'm_x': 0.0, 'm_y': 0.0, 'mouseFocus': False, 'onBorder': False, 'onResizeHandles': False, 'selected': False}]
+~~~~
+
+Sequences can have a len operator applied, and be indexed
+~~~~
+>>> len(minsky.model.items())
+1
+>>> minsky.model.items[0]()
+{'bb': {}, 'bookmark': False, 'deleteCallback': '', 'm_sf': 1.0, 'm_x': 0.0, 'm_y': 0.0, 'mouseFocus': False, 'onBorder': False, 'onResizeHandles': False, 'selected': False}
+>>> minsky.model.items[0].name()
+'hello'
+~~~~
+
+Maps can be indexed by their keys:
+~~~~
+>>> len(minsky.variableValues)
+3
+>>> minsky.variableValues.keys()
+[':hello', 'constant:one', 'constant:zero']
+>>> minsky.variableValues[':hello'].name()
+'hello'
+~~~~
+
+### enums
+
+enums are mapped to python strings. pyminsky has an enum dict containing all the enums defined in the system, and their possible values. 
+~~~~
+>>> pyminsky.enum
+{'::minsky::Canvas::LassoMode::type': ['none', 'lasso', 'itemResize'], '::minsky::ClickType::Type': ['onItem', 'onPort', 'outside', 'inItem', 'onResize', 'legendMove', 'legendResize'], '::minsky::GodleyAssetClass::AssetClass': ['noAssetClass', 'asset', 'liability', 'equity'], '::minsky::GodleyAssetClass::DisplayStyle': ['DRCR', 'sign'], '::minsky::Group::IORegion::type': ['none', 'input', 'output', 'topBottom'], '::minsky::JustificationStruct::Justification': ['left', 'right', 'centre'], '::minsky::Minsky::CmdData': ['no_command', 'is_const', 'is_setterGetter', 'generic'], '::minsky::Minsky::MemCheckResult': ['OK', 'proceed', 'abort'], '::minsky::OperationType::Group': ['general', 'constop', 'binop', 'function', 'reduction', 'scan', 'tensor', 'statistics'], '::minsky::OperationType::Type': ['constant', 'time', 'integrate', 'differentiate', 'data', 'ravel', 'euler', 'pi', 'zero', 'one', 'inf', 'percent', 'add', 'subtract', 'multiply', 'divide', 'min', 'max', 'and_', 'or_', 'log', 'pow', 'polygamma', 'lt', 'le', 'eq', 'userFunction', 'copy', 'sqrt', 'exp', 'ln', 'sin', 'cos', 'tan', 'asin', 'acos', 'atan', 'sinh', 'cosh', 'tanh', 'abs', 'floor', 'frac', 'not_', 'Gamma', 'fact', 'sum', 'product', 'infimum', 'supremum', 'any', 'all', 'infIndex', 'supIndex', 'runningSum', 'runningProduct', 'difference', 'differencePlus', 'innerProduct', 'outerProduct', 'index', 'gather', 'meld', 'merge', 'slice', 'size', 'shape', 'mean', 'median', 'stdDev', 'moment', 'histogram', 'covariance', 'correlation', 'linearRegression', 'numOps'], '::minsky::VariableType::Type': ['undefined', 'constant', 'parameter', 'flow', 'integral', 'stock', 'tempFlow', 'numVarTypes']}
+~~~~
+
+You can set/get their values like any other C++ type, but if you attempt to set an enum to a string value not in its range of values, nothing will happen, no error is raised.
+
+### Method calls
+C++ methods are called, and passed python parameters are converted into their C++ equivalents where possible, and an exception thrown where not. Mostly, the obvious thing will work, but some peculiarities can occur. For example if a method is overloaded with both an int argument and a double argument, then calling the method on 3 will call the int version, but calling it on 3.0 will call the double version. Sometimes it can be non-obvious which method will be called, so some experimentation is in order. Structs, and class public members on parameters can be set by passing a dict object. members not set within the dict are set to the default values, as though default constructed in C++.
+