---

Virtual Cell

VCell - a modeling and simulation framework for computational cell biology

The VCell is a comprehensive framework for modeling and simulating cell biology from biological pathways down to cell biophysics. VCell supports the biochemical network and rule-based modeling and electrophysiology in compartmental modeling and within cellular geometry.

Simulation capabilities include ODEs, Reaction-Diffusion equations within cellular geometry, Gillespie and Hybrid stochastic solvers, Particle-based spatial simulations, network free simulations, and cell kinematics (moving boundary problems).

Contents

• VCell software
• Download VCell
• Building and running VCell Client as a standalone tool
• IntelliJ Setup for VCell Client on Windows/Mac
• Eclipse Setup for VCell Client on Windows/Mac
• Building and Running VCell Server
• CLI Requirements
• Other Details
• License

VCell software consists of

1. a standalone modeling and simulation tool (vcell-client)
2. a shared server providing a centralized model database, cluster computing and shared storage (vcell-server, vcell-api)
3. simulation solvers written in C++/Fortran/Python and developed as part of the project as well as third party solvers and analysis.

Download VCell

• VCell which hosts a free VCell Server for cluster computing and shared database.
• Prebuilt installers for vcell-client are available for Windows, Mac and Linux.
• BioFormats jar (used by running VCell clients when importing image data, can't be shipped directly with VCell, license issue)

git clone https://github.com/virtualcell/vcell
cd vcell

Building, testing and running VCell on the command line

• This VCell GitHub project includes all Java/Python source code required to build both the VCell client and the VCell Server.
• The native simulation solvers each live in their own repository (vcell-fvsolver, vcell-ode, vcell-stochastic, vcell-nfsim, vcell-hy3s, vcell-chombo, vcell-mbsolver); the build downloads their release binaries into localsolvers/ (see localsolvers/README.md).
• Requirements: Git, Maven, Poetry, Python 3.10, Java 17

Build Java and Python

See docs/BUILDING.md for the full build, including why the Python packages must be built first, what dependency:copy-dependencies is for, and what a git worktree needs set up separately. The short version:

pip install -r requirements.txt     # installs poetry

# 1. Python packages, all seven
for p in vcell-cli-utils docker/swarm/vcell-admin pythonCopasiOpt/vcell-opt \
         pythonVtk python-utils python-restclient pythonData ; do
  ( cd "$p" && poetry env use 3.10 && poetry install ) || { echo "FAILED: $p"; break; }
done

# 2. Java
mvn --batch-mode clean install dependency:copy-dependencies -DskipTests=true

Test Java and Python

mvn test -Dgroups="Fast"

INSTALL_DIR=$(pwd)
for p in vcell-cli-utils docker/swarm/vcell-admin pythonCopasiOpt/vcell-opt \
         pythonVtk python-utils python-restclient pythonData ; do
  ( cd "${INSTALL_DIR}/$p" && poetry run python -m pytest )
done

Java tests failing with a missing Python module or solver binary usually means the Python packages above were not built — see docs/BUILDING.md.

Run the VCell client (connects to the VCell servers)

./vcell.sh

VCell client IntelliJ setup for Windows and Mac (follow command line instructions first)

Requirements: IntelliJ, Java 17, Python 3.10 and poetry

• Follow the instructions above for building Python packages with poetry
• Start IntelliJ
  • Open Project -> Navigate to vcell folder where VCell was installed and built at the previous step.
    • Edit Configurations -> "+" Application
      • Name: VCellClient
      • -cp -> choose vcell-admin, Java 17 SDK of vcell-admin module
      • Main class: org.vcell.standalone.VCellClientDevMain
      • Modify options -> check Add VM options
      • VM options:

        -Dlog4j.configurationFile=${INSTALL_DIR}/vcell-cli/src/main/resources/log4j2.xml
        -Dcli.workingDir=${INSTALL_DIR}/vcell-cli-utils
        -Dvcell.primarySimdatadir.internal=/path/to/local/simdata
        -Dvcell.secondarySimdatadir.internal=/path/to/local/simdata
        -Dvcell.server.dbConnectURL=jdbc:postgresql://localhost:5432/postgres
        -Dvcell.server.dbDriverName=org.postgresql.Driver
        -Dvcell.server.dbPassword=dbpassword
        -Dvcell.server.dbUserid=dbuser
        -Dvcell.server.id=TEST
        -Dvcell.softwareVersion=Dev_Version_7.5_build_00
        -Dvcell.mongodb.host=localhost
        -Dvcell.mongodb.host.internal=localhost
        -Dvcell.mongodb.port.internal=27019
        -Dvcell.mongodb.database=TEST
        -Dvcell.server.maxJobsPerScan=2
        

VCell client Eclipse setup for Windows and Mac (follow command line instructions first)

Requirements: Eclipse IDE for Java Developers and Java 17, Python 3.10 and poetry

• Follow the instructions above for building Python packages with poetry
• Start Eclipse
• During Eclipse setup, use an option -> Existing local repository, follow all next steps
• Make sure the project comes in as a Maven project (letter M on the top of the project, not J), otherwise, you need to add it to Maven
• Build the project in Eclipse (should start automatically, may come with several errors due to different build order).
• Errors in individual projects can be fixed by Maven -> Update Project for individual projects that display errors.
• Create a Debug configuration as an Application in IntelliJ.

Building and Running VCell Server

1. Service has 1 image and configuration, manages 1 or more containers, container is a running image
2. All services defined in ./swarm/docker-compose.yml (collection of services,volumes, dependencies,...)

VCell Server Installation General Requirements

• Linux
• Git, Maven, and Java JDK 17 or later to build vcell-client and vcell-server
• Docker (swarm mode)
• Singularity (Linux) or Singularity in a Virtual Machine (Macos needs VirtualBox and Vagrant)
• PostgreSQL or Oracle database
• SLURM service for batch scheduling
• Obtain an Install4J license if creating client installers

VCell CLI Requirements

1. VCell-CLI module requires python 3.10 and poetry

Other Details

1. Creating certs details
   1.1. (TLS/SSL website for (vcellapi.cam.uchc.edu,vcell-api.cam.uchc.edu)
   1.2. Microsoft authenticode codesigning (to prevent install4j from being rejected on windows clients)
   1.3. Apple codesigning for macos (prevents from mac refusing install4j install))
2. Understanding VCell services detailed instructions
3. NEW VCell Server Node configuration detailed instructions
   3.1. Create new Docker swarm with node or Add node to existing Docker swarm detailed instructions
   3.2. Finish NEW VCell Server Node configuration detailed instructions
4. Building VCell Client/Server Software detailed instructions
   4.1. Github/Travis/Appveyor/Dockerhub Instructions
5. Deploying VCell Client/Server software detailed instructions
   5.1. VCell System Flow-Control
6. Server Administration detailed instructions (.e.g restarting VCell services)
7. Debugging detailed instructions (.e.g debug vcell client/server)

License

Virtual Cell software is licensed under the MIT open source license.