Package: beam-viewer
SimWrapper Python ToolsOfficial python library for working with SimWrapper BEAM.SimWrapperis a data visualization tool for exploring large transport simulation results.Web browsers all block access to your local filesystem from external websites, for obvious security reasons. The SimWrapper website needs access to model run outputs on your filesystem. This program bridges that gap: it is a command-line tool that starts a local file server in a specific folder, so that you can access the files in that folder using SimWrapper.About this libraryThis library contains the "simwrapper" command-line tool, which allows browsing of local files on your PC/laptop using the SimWrapper website.We are at the very early stages of building this tool. The API will change, things will break, and there are certainly bugs.Our primary goal is to make it easy to get local simulation results viewable using the SimWrapper website.We have only tested this using Anaconda Python. Only Python 3.x is supported.InstallationInstallation requires thepippackage manager.Install usingpip install beam-viewerTo upgrade to the latest version,pip install --upgrade beam-viewerThis package includes an embedded copy of the Javascript code from the SimWrapper
project, available separately athttps://github.com/simwrapper/simwrapper. That code is under the
identical GNU GPL V3 and is embedded here with explicit permission of the author.Usagebeam-viewerknows three commands.beam-viewer servestarts a local file server in the current directory. Run this command, then browse to eitherhttps://vsp.berlin/simwrapperorhttps://activitysim.github.io/dashboardto view your local folder outputs.beam-viewer herestarts alocal copy of the SimWrapper websiteusually listening on port 8050. Run this command instead ofsimwrapper serveif you have a machine on your local network which contains outputs you'd like to view (such as a modeling server), and that machine has not been set up with any other file sharing software such as NGINX or Apache.This command is designed to support the use case where an agency has (1) a local network with files stored on a central "modeling server" or file server, and also (2) desktop machines or laptops on the local network that wish to access those files using SimWrapper.Note, it's not a battle-tested multi-threaded web proxy server such as Apache, NGINX, or Gunicorn. Ultimately you may decide that you want to put simwrapper behind a proxy server such as those listed, for improved performance, features, and security.beam-viewer open [beam|vsp|asim]opens a new web browser tab AND a local file server in the current directory. The site will only operate as long as you keep that local server running, so don't close the command window.To open on the BEAM site on the web, usebeam-viewer open beamYou can also runbeam-viewer openwithout specifying an external site. In this case, it will will serve everything from the localhost, including file contents and SimWrapper code itself. This is the same asbeam-viewer hereexcept it also opens a browser tab.All of these commands start a small local file server, listening on a local port number. The site will only operate as long as you keep that local server running: quitting the command with CTRL-C or closing the command window will shut down the server.SecurityWhenbeam-vieweris running, it listens for connections on your network interface. Your computer'sfirewall rules and router settingsdetermine whether other machines on the network can access the folder, or not.By default, almost all computers now run firewalls which block external access. If you want the files in your simwrapper folder to be available on your network, you will need to grant firewall permissions, generally meaning you need to authorize incoming network connections for the Python executable, and on the specific port used by SimWrapper.SimWrapper usually runs on ports 8000 and 8050. Starting multiple copies will increment the port numbers by one each time.Running as HTTPS - required for SafariSafari blocks HTTPS websites (such as SimWrapper VSP and ASIM) which access localhost resources such as this local simwrapper file server.We recommend using Google Chrome, Brave, and Microsoft Edge, because they are much faster than Safari or Firefox. But you can run beam-viewer in HTTPS mode by following these extra instructions.Simwrapper commands accept--keyand--certoptions to specify the two pieces of a PEM certicate. You can create a PEM certificate for "localhost" and install it in your browser's certificate database with the following commands.This requires Homebrew, which supplies thebrewcommand.brewinstallmkcertnss# installs mkcert commandmkcertlocalhost# Create PEM key/cert files for "localhost"mkcert-install# Installs certificates in browserThis creates two files:localhost.pemandlocalhost-key.pem. Move them somewhere where you cn find them.Now you can run simwrapper as follows:beam-viewer serve --cert localhost.pem --key localhost-key.pembeam-viewer open beam --cert localhost.pem --key localhost-key.pemThebeam-viewer herecommand does not use or support certificates.For help or supportSimWrapper is open source software with no guarantees, and is provided under the GNU GPL v3 license. You can post questions, bugs, or updates on the SimWrapper Github issue list, here:http://github.com/simwrapper/simwrapper/issues.Have fun!Developing the SimWrapper Python toolThe pythonbeam-viewertool contains a fully-built static copy of the SimWrapper website in thesimwrapper/staticfolder. Whenever you make changes to the SimWrapper website, you'll need to package up the changes, copy them into this Python project, and build the Python package.Here are the basic steps to do that:In the SimWrapper javascript project repo:Make any changes to theSimWrapper javascript codeas needed, and test vigorouslyEnsure that bothvite.config.jsandpublic/404.htmlare both set to have prefix "/" instead of "/simwrapper/" or "/dashboard/". The Python tool will not work if there is a URL prefix in the path.Runnpm run buildto compile everything into thedistfolder.Then in this Python repository:Delete all files in thesimwrapper/staticfolderDelete all files in thebuildfolderCopy entire contents from the SimWrapperdistfolder (above) to thesimwrapper/staticfolder hereMake any needed changes to the Python code in thesimwrapperfolder hereRunmake buildto generate the Python codeNow you can test your changes locally by runningpip install .from the root folder of this project. You probably want to be inside a python environment if you want to isolate your changes during testing.If everything is running smoothly, then push the project to pip and conda:Updating pipCommit all your changes: use semantic versioning commit messages ("fix: blah" and "feat: blah")Bump the version number withmake versionCommit the version bump, and push changes to GithubPush to PyPi (pip) withmake pushTake note of the SHA256 string for the newversion.tar.gzathttps://pypi.org/project/simwrapperwhich can be found on the "Download Files" pageUpdating condaModify the conda "feedstock" fork athttps://github.com/simwrapper/simwrapper-feedstock:Editrecipe/meta.yaml: you probably just need to change the version string and the SHA256The SHA256 is found onhttps://pypi.org/project/simwrapperon the Download Files pagePush to GithubCreate a pull request onhttps://github.com/conda-forge/simwrapper-feedstockMake notes in the PR description, checking off the relevant boxes.You don't need to do a "rerender" unless you've changed Python versions (I think)