Package: bettersis
BETTERSISBettersis, or bsis for short, is aninteractive shellthat allows you tocontrol SIS(the tool for synthesis and optimization of sequential circuits)
more easily than its default shell thanks to modern features such as:commandautocompletioncommandhistorycommandsuggestionsRead this README in:EnglishItalianoDisclaimer:I'm not affiliated with the SIS developers in any way.The aim of this software is to provide a better shell with modern features for SIS.IndexDescriptionRequirementsDevelopment requirementsInstallationUsagePersistent history across sessionsFound an issue?ChangelogAuthorDescriptionThis software provides a new interactive shell thatcontrols SIS in the backgroundusing thesiswrapperlibrary.I build thesiswrapperlibrary thanks to thepexpectlibrary,
a Python library that can easily be used
to control interactive shells by spawning and connecting to their process.The interactive shell is controlled by theBettersisclass
which uses theprompt_toolkitlibrary to show the prompt and
the bottom toolbar and provides history and autocompletion of commands.You can read more about betterSIS's code on readthedocsby clicking here.Go to the indexRequirementsUnix-like OSpexpect doesn't have all its features on Windows and SIS works best on linux OSesSIS, set in the path environment variable (callable with thesiscommand): the tool for synthesis and optimization of sequential circuitsYou candownload it hereOnly if you deside to install a version that is not the Snap store version.
The Snap store version is bundled with SIS.(snap ONLY for the Snap store version)Development requirementsthe requirements specified abovePython 3 (version >= 3.6)prompt-toolkit doesn't support older python 3 versionsthe siswrapper library for Python: controls SIS via Pythonthe prompt-toolkit library for Python: manages the modern shell and its features(PyInstaller - only if you need to build the executable)The OS you build the executable on should be the oldest possibile to support more updated OSes
(builds are not backwards compatible)certifi: a library that manages SSL/TLS certificates. It is necessary to connect to Github Release to check if there are updates.This is only needed for old OSes that don't have up to date certificatesGo to the indexInstallationYou can also see a summary of thedifferences between installation methods hereAfter reading the summary you can follow the instructions to install betterSIS using your prefered method and read its advantages and disadvantages down below.You can:(Easiest and best option) Install the software from the Snap store.From the command line, execute this command:sudo snap install bettersisYou need to have snap installed. You can install byfollowing the instructions here.Note that you probably already have it installed. (especially if you are using a recent version of an Ubuntu based distro)From the Graphical User Interface:Click this button:Then click on the "Install" button on the top right side of the webpageClick on "View in Desktop Store" and "Choose an app"Choose "Ubuntu software" OR "Handler for snap:// URIs" OR "Snap Store"These options are written in order of preference: if the first option is not available, pick the second one, etc... If none of the options are available you should probably install betterSIS using the command above.Click on the "Install" button(Optional) If you want to, you can change the permissions by clicking the "Permissions" buttonI recommend to only enable/disable the "read/write permissions on removable media" one to access BLIF files inside USBs or/mnt/directories (if you have for example a Virtualbox shared folder).The other permissions are needed to access BLIF files inside the home directory and to check if updates are available (Changing these might stop the application from working correctly OR it could become un-usable until you re-enable the permissions again)Advantages over the other options:Execute the shell from everywhere by executing thebettersiscommandThere's no need to install Python and the dependenciesSIS is bundled together with betterSIS: there is no need to install it manuallyIf you already have SIS installed don't worry: they don't conflict.Automatic updates: when an update is available it will be installed automatically.This allows you to always have the latest bug fixes and features.Compatible with all the OS distributions that snap is compatible withDisadvantages:Might use (slightly) more resources than the other optionsSIS is bundled together with betterSIS: it occupies more disk space (3.08 MB more)Automatic updates: there's no way of turning them on and offin a convenient waysnap is required to install itMost Ubuntu based distros and others alreadyhave it installed by defaultAdvantage/Disadvantage:Snaps are very limited in permissions. This means that you can easily find Permission Errors if you try to open files in folders in which you don't have permissions to enter as a user.I suggest you to open and use betterSIS from a folder that is somewhere inside the home directory (for example/home/myuser/Documents/myprojects/sis_projects) and to NOT use sudo to open bettersis.You should also be able to give permissions to open and use betterSIS in removable media by
following the 6th step described above "Advantages over the other options"You can uninstall it by opening the betterSIS page on the Ubuntu Store/Snap store and clicking the remove/uninstall button.You can follow the same steps to install it and then click on remove/uninstall instead of "install" at the 5th step.You can also uninstall it by executing this command:snap remove bettersisUse the AppImage executable:Download the .AppImage file from theGithub Release page here.Ignore the.AppImage.zsyncfile: it is used by the AppImage to find updates and you DON'T need to download itYou can start the shell by executing the file:./Bettersis-<version>-x86_64.AppImageReplace<version>with the version number (like1.2.1)If the command says "Permission denied", you need to set the file type to executable using this command:chmod +x Bettersis-<version>-x86_64.AppImageMake sure that you are in the same directory as the fileAdvantages:No installation requiredThere's no need to install Python and its dependenciesYou can update the AppImage by using thebsis_updatecommand from the betterSIS shellDisadvantages:Hard to use because of the unknown pathYou could add it to the path environment variable,
otherwise you have to call it using the full path or you
have to read blif files using their full pathOn many distros you can put the executable inside thebinfolder inside your home folder ($HOME): this allows you to execute thebsiscommand from every folder. The result is the same as installing betterSIS and executing that command.Delete the file to "uninstall" betterSIS.Install the software as a DEB packageDownload the .deb package file from theGithub Release page hereand
install it using the following command:sudo dpkg -i <file>Replace<file>with the path of the .deb fileYou can repeat this command on a new version to update
the software.It is necessary to use the super user to install the software,
(the OS will ask for the root password)You can also install the .deb file by double clicking on it and then click "Install"Advantages:Execute the shell from everywhere by executing thebsiscommand on the terminal.There's no need to install Python and the dependencies to executebettersis.pyDisadvantages:Might not be 100% compatible with all the OSes / OSes versions.It is definitely NOT compatible with distros that are NOT based on debian.No automatic updates: you need to manually download the DEB package and install it.You can uninstall the shell by executing this command:dpkg --remove bettersisUse the PyInstaller executableDownload the PyInstaller executable from theGithub Release page here(its the one called "bsis" with no file extension)You can start the shell by executing the file:./bsisIf the command says "Permission denied", you need to set the file type to executable using this command:chmod +x bsisMake sure that you are in the same directory as the fileAdvantages:No installation requiredThere's no need to install Python and the dependencies to executebettersis.pyDisadvantages:Hard to use because of the unknown pathYou could add it to the path environment variable,
otherwise you have to call it using the full path or you
have to read blif files using their full pathNo automatic updates: you need to manually download the new version and replace the old oneOn many distros you can put the executable inside thebinfolder inside your home folder ($HOME): this allows you to execute thebsiscommand from every folder. The result is the same as installing betterSIS and executing that command.Delete the file to "uninstall" betterSIS.Use the source code:Download this repositoryInstall the dependencies (better if you use a virtual environment for Python) using the following command:pip3 install -r requirements.txtBe sure that the current working directory is the repository rootExecutebettersis.py:python3 bettersis.pyAdvantages:It's the only way to develop improvements for this softwareDisadvantages:Hard to use because of the unknown pathYou could add it to the path environment variable,
otherwise you have to call it using the full path or you
have to read blif files using their full pathYou need to install Python and its dependencies(there's aPyPI versionbut you shouldn't use it. I've created it to register the name there and to avoid possible confusion)It might also come in handy in the future if I need to create a new installation methodGo to the indexUsageExecute thebettersisinteractive shellYou can execute it using:Python (if you want to execute this software from source code) orbsiscommand (ifbettersishas been installed using the .deb file) or./bsiscommand (if you want to execute Pyinstaller's executable file) orIf the executable is in a path which is inside the $PATH environment variable then you can simply call it using thebsiscommandbettersiscommand (if you installed the snap version)Now you can use the shell has if it was the normal SIS shell:
start reading files (usingread_blif), optimize circuits,
simulate them, ...You can see a usage example in the gif at the start
of this README.You can use thehelpcommand to list the old SIS command and the new betterSIS commands with a small description.If that description is not sufficient you can probably find more information about it in this document. If more details are needed please create an issue.There are also some tutorials on readthedocs (in italian):click herePersistent history across sessionsThis feature allows you to execute commands, close betterSIS, re-open it later and find the old commands using the up/down arrow keys.This feature is disabled by default because betterSIS needs to write the~/.bsis_historyfile to save the old commands and the user might not want that.To enable this feature you need to set the "BSIS_HISTORY_ENABLED" environment variable to "true".To set the environment variable modify the~/.bashrcfile (or an equivalent file based on your default OS shell) and
add this lineexport BSIS_HISTORY_ENABLED=trueto the end of the file.The default history file size limit is 100 KB but you can set it using the "BSIS_HISTORY_SIZELIMIT" environment variable (the minimum limit is 1000 bytes)To change the history file size limit add this line to the~/.bashrcfile (or equivalent):export BSIS_HISTORY_SIZELIMIT=10000.Replace "10000" with the number of bytes you wish to cap the file size.Close and then open the terminal to use the new changes.Go to the indexFound an issue?Please create a new issue with all the details here:https://github.com/mario33881/betterSIS/issuesIf you used:the snap version: execute the following command on the terminal to create a log file and then add its content to the issuecat /var/log/syslog | grep "bettersis" > pybettersis.logthe PyInstaller version: execute the following command on the terminal to create a log file and then add its content to the issuecat /var/log/syslog | grep "bettersis" > pybettersis.logthe DEB package version: add the content of the/var/log/pybettersis/pybettersis.logfile to the issueGo to the indexChangelog2021-09-07 1.2.1:Changes:Now the original output is kept completely intact (included warnings) and at the end of the command execution warnings are shown a second time.Warnings were hidden during the command execution because they were considered redondant (to the developer) but having the full "history" of the output
and then a brief summary of Warnings and/or errors makes more sense.Features:Added persistent command history across different sessions (they are saved inside the~/.bsis_historyfile).It is disabled by default and you can enable it by setting the "BSIS_HISTORY_ENABLED" environment variable to "true".Check the documentation on how to enable itand how to set the history size limit.Added thebsis_tutorialscommand: it opens the browser on theSIS tutorials webpageAdded thebsis_documentationcommand: it opens the browser on thebetterSIS documentation webpageAdded thebsis_releasescommand: it opens the browser on thedownload page for the latest betterSISAdded thebsis_checkblifcommand: uses the blifparser library as a basic parser/validation tool for BLIF filesNow thehelpcommand also shows betterSIS commandsNew release on the Snap store. You can now install this software using thesnap install bettersiscommand or using the Snap Store GUI.New release as an AppImage. You can think of it as having an updatable PyInstaller version.Use thebsis_updateto update your AppImage when an update is availableAdded two arguments to betterSIS: the--debugflag used to write more details in the log file and the--verbosedebugflag to also show debug information inside the shell--verbosedebugonly works when you also use the--debugflagThe simple text editor now shows the text "Saved to file" when the user saves the file using Ctrl+SFixes:Now the program can correctly check if an update is available.Fixed theUnicodeEncodeError: 'ascii' codec can't encode character in position 0: ordinal not in range(128)errorThis happened because of the ASCII art that is shown when bettersis is executed:
the terminal must be set to use an UTF-8 language using the$LANGenvironment variable to be able to show those ASCII characters.Now the ASCII art is simply not shown if the user's terminal doesn't support it.(siswrapper) Fixed timeout error on commands that gave paginated outputs such as thehelp read_blifcommand.2021-03-17 1.2.0:Features:Added thelscommand: it shows files and directories in the given/current pathAdded thecdcommand: you can use it to navigate directories from betterSISAdded theeditcommand: opens the specified file with a simple text editorEditor's features: syntax highlighting, basic edit/save functionality, use the tab key to write/complete keywords(siswrapper feature) Addedbsis_scriptcommand. Its accepted parameters are:fsm_autoencoding_area, useful for FSM circuits: minimizes states, automatically encodes states, optimizes area and maps the circuit by area (synch library)Executed commands:state_minimize stamina,state_assign jedi,source script.rugged,read_library synch.genlib,map -m 0 -W -sfsm_autoencoding_delay, useful for FSM circuits: minimizes states, automatically encodes states, optimizes delay and maps the circuit by delay (synch library)Executed commands:state_minimize stamina,state_assign jedi,reduce_depth,source script.rugged,read_library synch.genlib,map -n 1 -W -sfsm_area, useful for FSM circuits: minimizes states, uses manual states encoding, optimizes area and maps the circuit by area (synch library)Executed commands:state_minimize stamina,stg_to_network,source script.rugged,read_library synch.genlib,map -m 0 -W -sfsm_delay, useful for FSM circuits: minimizes states, uses manual states encoding, optimizes delay and maps the circuit by delay (synch library)Executed commands:state_minimize stamina,stg_to_network,reduce_depth,source script.rugged,read_library synch.genlib,map -n 1 -W -slgate_area_mcnc, useful for combinational circuits: optimizes area and maps the circuit by area (mcnc library)Executed commands:source script.rugged,read_library mcnc.genlib,map -m 0 -W -slgate_delay_mcnc, useful for combinational circuits: optimizes delay and maps the circuit by delay (mcnc library)Executed commands:reduce_depth,source script.rugged,read_library mcnc.genlib,map -n 1 -W -slgate_area_synch, useful for combinational circuits: optimizes area and maps the circuit by area (synch library)Executed commands:source script.rugged,read_library synch.genlib,map -m 0 -W -slgate_delay_synch, useful for combinational circuits: optimizes delay and maps the circuit by delay (synch library)Executed commands:reduce_depth,source script.rugged,read_library synch.genlib,map -n 1 -W -sfsmd_area, useful for FSMD circuits (circuits which include datapaths and an FSM): optimizes area and maps the circuit by area (synch library)Executed commands:source script.rugged,read_library synch.genlib,map -m 0 -W -sfsmd_delay, useful for FSMD circuits (circuits which include datapaths and an FSM): optimizes delay and maps the circuit by delay (synch library)Executed commands:reduce_depth,source script.rugged,read_library synch.genlib,map -n 1 -W -sThis command also shows which command is executed and the statistics after some commandsPartial and full results are written to new BLIF files.WARNING! These commands are executed in this order, thus does NOT guarantee the best result: multi-level minimization is not perfect!
to obtain better results you should try to execute these commands manually in a different order (try also to execute them more than once)(siswrapper feature) Now this library verifies if the stg_to_network command is successfulFixes:(siswrapper fix) Now thewrite_eqncommand gives the expected result when used to output to a file.Before this fix thewrite_blifmethod was executed instead of the correct method(siswrapper fix) When SIS is not installed the error message shows exactly what the problem is(siswrapper fix) If you call thewrite_eqnandwrite_blifmethod without parameters the output doesn't contain the command.(siswrapper fix) Can't execute the rugged script if no file as been read with a read command(siswrapper fix) When you execute a read command, this library calls theresetmethod to close the SIS session and
open a new session inside the folder of the input fileThis "fixes" the ".search x file not found" error when you try to read a file that is in another folder and contains the .search keyword.This error was normal but not intuitive (because the imported file was present inside the same folder as the input file but not inside the current folder).
It was the original SIS behaviour.(siswrapper fix) The output of theprint_statscommand couldn't be intepreted as correct when the circuit had more than a 10000 literals/statesThe output was correct but the program reported it as an errorKnown bugs:The executable version of betterSIS (both the deb package and the PyInstaller executable) can't correctly connect to Github Release to check for updates (SSL verification error)This will be fixed in the next version (for now you need to manually check if an update is available)2021-01-09 1.1.0:Features:Added logs to syslog to help solving problems (and/var/log/pybettersis/pybettersis.logfor .deb package installations)An "Update is available" message is shown when a new Github Release is onlineFiles are shown as parameters (for faster workflow)Fixes:simcommand is treated the same as thesimulatecommandsiswrapper 1.1.1can manage FSM outputs (fix:TypeError: 'NoneType' object is not subscriptable)Builds are made on an older OS (Ubuntu 12.04) to improve OS versions supportThis should fix this problem:Error loading Python lib [...] GLIBC_2.29 not found2020-11-14 1.0.0:First commitGo to the indexAuthorStefano Zenaro (mario33881)