From 923f3066131b93bd028f17918c3ae385c7fe574b Mon Sep 17 00:00:00 2001 From: pgleeson Date: Mon, 20 May 2024 11:17:52 +0100 Subject: [PATCH 01/12] Test ow-0.9.5 branches --- Dockerfile | 7 ++++--- Dockerfile_intel | 6 +++--- VERSION | 2 +- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/Dockerfile b/Dockerfile index 1a4bf89..943ab18 100644 --- a/Dockerfile +++ b/Dockerfile @@ -20,6 +20,7 @@ RUN mkdir -p /etc/sudoers.d && \ ENV DEBIAN_FRONTEND noninteractive # TODO: change + ################################################################################ ######## Update/install essential libraries @@ -52,7 +53,7 @@ RUN sudo update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 10 ################################################################################ ######## Install NEURON simulator -RUN pip3 install neuron==8.0.1 +RUN pip3 install neuron==8.2.2 ################################################################################ @@ -60,7 +61,7 @@ RUN pip3 install neuron==8.0.1 RUN git clone https://github.com/openworm/c302.git && \ cd c302 && \ - git checkout ow-0.9.4 && \ + git checkout ow-0.9.5 && \ sudo pip install . # Note: pyNeuroML installed with the above library @@ -74,7 +75,7 @@ RUN owm bundle remote --user add ow 'https://raw.githubusercontent.com/openworm/ RUN git clone https://github.com/openworm/sibernetic.git && \ cd sibernetic && \ - git checkout ow-0.9.4 # fixed to a specific branch + git checkout ow-0.9.5 # fixed to a specific branch ################################################################################ diff --git a/Dockerfile_intel b/Dockerfile_intel index 3ffc2b7..bc26131 100644 --- a/Dockerfile_intel +++ b/Dockerfile_intel @@ -53,7 +53,7 @@ RUN sudo update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 10 ################################################################################ ######## Install NEURON simulator -RUN pip3 install neuron==8.0.1 +RUN pip3 install neuron==8.2.2 ################################################################################ @@ -61,7 +61,7 @@ RUN pip3 install neuron==8.0.1 RUN git clone https://github.com/openworm/c302.git && \ cd c302 && \ - git checkout ow-0.9.4 && \ + git checkout ow-0.9.5 && \ sudo pip install . # Note: pyNeuroML installed with the above library @@ -75,7 +75,7 @@ RUN owm bundle remote --user add ow 'https://raw.githubusercontent.com/openworm/ RUN git clone https://github.com/openworm/sibernetic.git && \ cd sibernetic && \ - git checkout ow-0.9.4 # fixed to a specific branch + git checkout ow-0.9.5 # fixed to a specific branch ################################################################################ diff --git a/VERSION b/VERSION index a602fc9..b0bb878 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.9.4 +0.9.5 From edc51240d7d6b1b1bbd1a014e7fdfc12037d9a52 Mon Sep 17 00:00:00 2001 From: pgleeson Date: Fri, 31 May 2024 12:24:01 +0100 Subject: [PATCH 02/12] Tweak tests; back to neuron 8.0.1 --- .github/workflows/docker-image-intel.yml | 4 ++-- .github/workflows/docker-image-quickrun.yml | 4 ++-- .github/workflows/docker-image.yml | 4 ++-- Dockerfile | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docker-image-intel.yml b/.github/workflows/docker-image-intel.yml index a9d5a0a..ff0975f 100644 --- a/.github/workflows/docker-image-intel.yml +++ b/.github/workflows/docker-image-intel.yml @@ -1,4 +1,4 @@ -name: Docker Image Test Build - Intel drivers +name: Docker Image Build - Intel drivers on: push: @@ -18,7 +18,7 @@ jobs: - name: Build the Docker image run: | chmod a+w output/ - ls -alt + ls -alth ./build_intel.sh - name: Info on Docker images diff --git a/.github/workflows/docker-image-quickrun.yml b/.github/workflows/docker-image-quickrun.yml index 31f1cfc..4c07b99 100644 --- a/.github/workflows/docker-image-quickrun.yml +++ b/.github/workflows/docker-image-quickrun.yml @@ -1,4 +1,4 @@ -name: Docker Image Test - quick +name: Docker Image Quick Run on: push: @@ -17,7 +17,7 @@ jobs: - name: Build the Docker image run: | chmod a+w output/ - ls -alt + ls -alth ./build.sh - name: Info on Docker images run: | diff --git a/.github/workflows/docker-image.yml b/.github/workflows/docker-image.yml index 3bd3c08..f5ea7d3 100644 --- a/.github/workflows/docker-image.yml +++ b/.github/workflows/docker-image.yml @@ -1,4 +1,4 @@ -name: Docker Image Test Build +name: Docker Image Build & Run on: push: @@ -17,7 +17,7 @@ jobs: - name: Build the Docker image run: | chmod a+w output/ - ls -alt + ls -alth ./build.sh - name: Info on Docker images run: | diff --git a/Dockerfile b/Dockerfile index 943ab18..478ea2a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -53,7 +53,7 @@ RUN sudo update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 10 ################################################################################ ######## Install NEURON simulator -RUN pip3 install neuron==8.2.2 +RUN pip3 install neuron==8.0.1 ################################################################################ From cb15aeaf0b610629c7feaa01b1b54375b31e8258 Mon Sep 17 00:00:00 2001 From: Syed Hussain Ather Date: Thu, 6 Jun 2024 09:49:44 -0400 Subject: [PATCH 03/12] updated with more detail --- README.md | 94 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 50 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 6a6df24..df6bb94 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ +Here is the updated `README.md` file with the provided text integrated: + +```markdown ![OpenWorm](http://www.openworm.org/img/OpenWormLogo.png) [![Docker Image CI](https://github.com/openworm/OpenWorm/actions/workflows/docker-image.yml/badge.svg)](https://github.com/openworm/OpenWorm/actions/workflows/docker-image.yml) [![Docker Image Test - quick](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-quickrun.yml/badge.svg)](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-quickrun.yml) [![Docker Image Test Build - Intel drivers](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-intel.yml/badge.svg)](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-intel.yml) -About **OpenWorm** ------------------- +## About **OpenWorm** [OpenWorm](http://openworm.org) aims to build the first comprehensive computational model of *Caenorhabditis elegans* (*C. elegans*), a microscopic roundworm. With only a thousand cells, it solves basic problems such as feeding, mate-finding and predator avoidance. Despite being extremely well-studied in biology, a deep, principled understanding of the biology of this organism remains elusive. @@ -12,9 +14,9 @@ We are using a bottom-up approach, aimed at observing the worm behaviour emerge You can earn a badge with us simply by trying out this package! Click on the image below to get started. [![OpenWorm Docker Badge](https://raw.githubusercontent.com/openworm/OpenWorm/master/img/ow-docker-badge.png)](https://www.badgelist.com/OpenWorm/OpenWorm-Docker-Apprentice) -Quickstart ----------- -We have put together a [Docker container](https://hub.docker.com/r/openworm/openworm) that pulls together the major components of our simulation and runs it on your machine. When you get it all running it does the following: +## Quickstart + +We have put together a [Docker container](https://hub.docker.com/r/openworm/openworm) that pulls together the major components of our simulation and runs it on your machine. When you get it all running it does the following: 1. Run our nervous system model, known as [c302](https://github.com/openworm/c302), on your computer. 2. In parallel, run our 3D worm body model, known as [Sibernetic](https://github.com/openworm/sibernetic), on your computer, using the output of the nervous system model. @@ -27,89 +29,93 @@ We have put together a [Docker container](https://hub.docker.com/r/openworm/open -**NOTE**: Running the simulation for the full amount of time would produce content like the above. However, in order to run in a reasonable amount of time, **the default run time for the simulation is limited**. As such, you will see only a partial output, equivalent to about 5% of run time, compared to the examples above. To extend the run time, use the `-d` argument as described below. +**NOTE**: Running the simulation for the full amount of time would produce content like the above. However, in order to run in a reasonable amount of time, **the default run time for the simulation is limited**. As such, you will see only a partial output, equivalent to about 5% of run time, compared to the examples above. To extend the run time, use the `-d` argument as described below. -**Installation** +## Installation -Pre-requisites: +### Pre-requisites -1) You should have at least 60 GB of free space on your machine and at least 2GB of RAM -2) You should be able to clone git repositories on your machine. [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), or [this GUI](https://desktop.github.com/) may be useful. +1. You should have at least 60 GB of free space on your machine and at least 2GB of RAM. +2. You should be able to clone git repositories on your machine. [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), or [this GUI](https://desktop.github.com/) may be useful. -To Install: +### To Install 1. Install [Docker](http://docker.com) on your system. -2. If your system does not have enough free space, you can use -an external hard disk. On MacOS X, the location for image storage -can be specified in the [Advanced Tab](https://forums.docker.com/t/change-docker-image-directory-for-mac/18891/15) in Preferences. See [this thread](https://forums.docker.com/t/how-do-i-change-the-docker-image-installation-directory/1169/18) -in addition for Linux instructions. +2. If your system does not have enough free space, you can use an external hard disk. On MacOS X, the location for image storage can be specified in the [Advanced Tab](https://forums.docker.com/t/change-docker-image-directory-for-mac/18891/15) in Preferences. See [this thread](https://forums.docker.com/t/how-do-i-change-the-docker-image-installation-directory/1169/18) in addition for Linux instructions. -**Running** +## Running 1. Ensure the Docker daemon is running in the background (on MacOS/Windows there should be an icon with the Docker whale logo showing in the menu bar/system tray). -2. Open a terminal and run: `git clone http://github.com/openworm/openworm`; `cd openworm` +2. Open a terminal and run: + ```bash + git clone http://github.com/openworm/openworm + cd openworm + ``` 3. Optional: Run `./build.sh` (or `build.cmd` on Windows). If you skip this step, it will download the latest released Docker image from the [OpenWorm Docker hub](https://hub.docker.com/r/openworm/openworm). 4. Run `./run.sh` (or `run.cmd` on Windows). 5. About 5-10 minutes of output will display on the screen as the steps run. -6. The simulation will end. Run `stop.sh` (`stop.cmd` on Windows) on your system to clean up the running container. +6. The simulation will end. Run `stop.sh` (`stop.cmd` on Windows) on your system to clean up the running container. 7. Inspect the output in the `output` directory on your local machine. -**Advanced** +## Advanced -***Arguments*** +### Arguments -* -d [num] : Use to modify the duration of the simulation in milliseconds. Default is 15. Use 5000 to run for time to make the full movie above (i.e. 5 seconds). +- `-d [num]`: Use to modify the duration of the simulation in milliseconds. Default is 15. Use 5000 to run for time to make the full movie above (i.e. 5 seconds). -***Other things to try*** +### Other things to try -* Open a terminal and run `./run-shell-only.sh` (or `run-shell-only.cmd` on Windows). This will let you log into the container before it has run `master_openworm.py`. From here you can inspect the internals of the various checked out code bases and installed systems and modify things. Afterwards you'll still need to run `./stop.sh` to clean up. -* If you wish to modify what gets installed, you should modify `Dockerfile`. If you want to modify what runs, you should modify `master_openworm.py`. Either way you will need to run `build.sh` in order to rebuild the image locally. Afterwards you can run normally. +- Open a terminal and run `./run-shell-only.sh` (or `run-shell-only.cmd` on Windows). This will let you log into the container before it has run `master_openworm.py`. From here you can inspect the internals of the various checked out code bases and installed systems and modify things. Afterwards, you'll still need to run `./stop.sh` to clean up. +- If you wish to modify what gets installed, you should modify `Dockerfile`. If you want to modify what runs, you should modify `master_openworm.py`. Either way you will need to run `build.sh` in order to rebuild the image locally. Afterwards, you can run normally. -### FAQ +## FAQ #### **What is the Docker container?** -The Docker container is a self-contained environment in which you can run OpenWorm simulations. It's fully set up to get you started by following the steps above. At the moment, -it runs simulations and produces visualizations for you, but these visualizations must be viewed outside of the Docker container. While you do not need to know -much about Docker to use OpenWorm, if you are planning on working extensively with the platform, you may benefit -from understanding some basics. [Docker Curriculum](https://docker-curriculum.com) -is an excellent tutorial for beginners that is straightforward to work through (Sections 1 - 2.5 are plenty sufficient). +The Docker container is a self-contained environment in which you can run OpenWorm simulations. It's fully set up to get you started by following the steps above. At the moment, it runs simulations and produces visualizations for you, but these visualizations must be viewed outside of the Docker container. While you do not need to know much about Docker to use OpenWorm, if you are planning on working extensively with the platform, you may benefit from understanding some basics. [Docker Curriculum](https://docker-curriculum.com) is an excellent tutorial for beginners that is straightforward to work through (Sections 1 - 2.5 are plenty sufficient). #### **Is it possible to modify the simulation without having to run `build.sh`?** -Yes, but it is marginally more complex. The easiest way is to modify anything in the Docker container once you are inside of it - it will work just like a bash shell. If you want to modify any code in the container, you'll need to use an editor that runs in the terminal, like nano. Once you've modified something in the container, you don't need to re-build. However, if you run `stop.sh` once you exit, those changes will be gone. +Yes, but it is marginally more complex. The easiest way is to modify anything in the Docker container once you are inside of it - it will work just like a bash shell. If you want to modify any code in the container, you'll need to use an editor that runs in the terminal, like nano. Once you've modified something in the container, you don't need to re-build. However, if you run `stop.sh` once you exit, those changes will be gone. #### **How do I access more data than what is already output?** -The simulation by default outputs only a few figures and movies to your home system (that is, outside of the Docker container). If you want to access the entire output of the simulation, you will need to copy it from the Docker container. +The simulation by default outputs only a few figures and movies to your home system (that is, outside of the Docker container). If you want to access the entire output of the simulation, you will need to copy it from the Docker container. -For example, say you want to extract the worm motion data. This is contained in the file `worm_motion_log.txt`, which is found in the `/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt`. The directory `[SPECIFIC_TIMESTAMPED_DIRECTORY]` will have a name like `C2_FW_2018_02-12_18-36-32`, and its name can be found by checking the `output` directory. This is actually the main output directory for the simulation, and contains all output, including cell modelling and worm movement. +For example, say you want to extract the worm motion data. This is contained in the file `worm_motion_log.txt`, which is found in the `/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt`. The directory `[SPECIFIC_TIMESTAMPED_DIRECTORY]` will have a name like `C2_FW_2018_02-12_18-36-32`, and its name can be found by checking the `output` directory. This is actually the main output directory for the simulation, and contains all output, including cell modelling and worm movement. Once the simulation ends and you exit the container with `exit`, but before you run `stop.sh`, run the following command from the openworm-docker-master folder: -`docker cp openworm:/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt ./worm_motion_log.txt` +```bash +docker cp openworm:/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt ./worm_motion_log.txt +``` -This will copy the file from the Docker container, whose default name is `openworm`. **It is crucial that you do not run `stop.sh` before trying to get your data out (see below)** +This will copy the file from the Docker container, whose default name is `openworm`. **It is crucial that you do not run `stop.sh` before trying to get your data out (see below)** #### **What is the difference between `exit` and `stop.sh`?** -When you are in the Docker Container `openworm`, and are done interacting with it, you type `exit` to return to your system's shell. This stops execution of anything in the container, and that container's status is now `Exited`. If you try to re-start the process using `run-shell-only.sh`, you will get an error saying that the container already exists. You can choose, at this point, to run `stop.sh`. Doing so will remove the container and any files associated with it, allowing you to run a new simulation. However, if you don't want to remove that container, you will instead want to re-enter it. +When you are in the Docker Container `openworm`, and are done interacting with it, you type `exit` to return to your system's shell. This stops execution of anything in the container, and that container's status is now `Exited`. If you try to re-start the process using `run-shell-only.sh`, you will get an error saying that the container already exists. You can choose, at this point, to run `stop.sh`. Doing so will remove the container and any files associated with it, allowing you to run a new simulation. However, if you don't want to + + remove that container, you will instead want to re-enter it. #### **How do I enter a container I just exited?** -If you run `stop.sh` you'll delete your data and reset the container for a new run. If, however, you don't want to do that, you can re-enter the Docker container like this: +If you run `stop.sh` you'll delete your data and reset the container for a new run. If, however, you don't want to do that, you can re-enter the Docker container like this: - docker start openworm # Restarts the container - docker exec -it openworm /bin/bash # Runs bash inside the container +```bash +docker start openworm # Restarts the container +docker exec -it openworm /bin/bash # Runs bash inside the container +``` -This tells Docker to start the container, to *execute* commands (`exec`) with an *interactive, tty* (`-it`) bash (`bash`) shell in the container `openworm`. +This tells Docker to start the container, to *execute* commands (`exec`) with an *interactive, tty* (`-it`) bash (`bash`) shell in the container `openworm`. You'll be able to interact with the container as before. -Documentation -------------- -to find out more about OpenWorm, please see the documentation at [http://docs.openworm.org](http://docs.openworm.org) or [join us on Slack](http://bit.ly/OpenWormVolunteer). +## Documentation -This repository also contains project-wide tracking via high-level [issues](https://github.com/openworm/OpenWorm/issues) and [milestones](https://github.com/openworm/OpenWorm/milestones). +To find out more about OpenWorm, please see the documentation at [http://docs.openworm.org](http://docs.openworm.org) or [join us on Slack](http://bit.ly/OpenWormVolunteer). +This repository also contains project-wide tracking via high-level [issues](https://github.com/openworm/OpenWorm/issues) and [milestones](https://github.com/openworm/OpenWorm/milestones). +``` +You can now save this updated `README.md` file, commit it to your local repository, push to your fork, and then create a pull request to contribute to the OpenWorm project. \ No newline at end of file From bce13e102ec1a769d366ecd9fb1ce55d16cef0ed Mon Sep 17 00:00:00 2001 From: Syed Hussain Ather Date: Thu, 6 Jun 2024 09:54:35 -0400 Subject: [PATCH 04/12] more detailed and user firendly instructions --- README.md | 43 ++++++++++++++++++++----------------------- 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index df6bb94..d36ab32 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,3 @@ -Here is the updated `README.md` file with the provided text integrated: - -```markdown ![OpenWorm](http://www.openworm.org/img/OpenWormLogo.png) [![Docker Image CI](https://github.com/openworm/OpenWorm/actions/workflows/docker-image.yml/badge.svg)](https://github.com/openworm/OpenWorm/actions/workflows/docker-image.yml) [![Docker Image Test - quick](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-quickrun.yml/badge.svg)](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-quickrun.yml) [![Docker Image Test Build - Intel drivers](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-intel.yml/badge.svg)](https://github.com/openworm/OpenWorm/actions/workflows/docker-image-intel.yml) @@ -9,16 +6,16 @@ Here is the updated `README.md` file with the provided text integrated: [OpenWorm](http://openworm.org) aims to build the first comprehensive computational model of *Caenorhabditis elegans* (*C. elegans*), a microscopic roundworm. With only a thousand cells, it solves basic problems such as feeding, mate-finding and predator avoidance. Despite being extremely well-studied in biology, a deep, principled understanding of the biology of this organism remains elusive. -We are using a bottom-up approach, aimed at observing the worm behaviour emerge from a simulation of data derived from scientific experiments carried out over the past decade. To do so, we are incorporating the data available from the scientific community into software models. We are also forging new collaborations with universities and research institutes to collect data that fill in the gaps. +We are using a bottom-up approach, aimed at observing the worm behavior emerge from a simulation of data derived from scientific experiments carried out over the past decade. To do so, we are incorporating the data available from the scientific community into software models. We are also forging new collaborations with universities and research institutes to collect data that fill in the gaps. You can earn a badge with us simply by trying out this package! Click on the image below to get started. [![OpenWorm Docker Badge](https://raw.githubusercontent.com/openworm/OpenWorm/master/img/ow-docker-badge.png)](https://www.badgelist.com/OpenWorm/OpenWorm-Docker-Apprentice) ## Quickstart -We have put together a [Docker container](https://hub.docker.com/r/openworm/openworm) that pulls together the major components of our simulation and runs it on your machine. When you get it all running it does the following: +We have put together a [Docker container](https://hub.docker.com/r/openworm/openworm) that pulls together the major components of our simulation and runs it on your machine. When you get it all running, it does the following: -1. Run our nervous system model, known as [c302](https://github.com/openworm/c302), on your computer. +1. Run our nervous system model, known as [c302](https://github.com/openworm/c302), on your computer. 2. In parallel, run our 3D worm body model, known as [Sibernetic](https://github.com/openworm/sibernetic), on your computer, using the output of the nervous system model. 3. Produce graphs from the nervous system and body model that demonstrate its behavior on your computer for you to inspect. 4. Produce a movie showing the output of the body model. @@ -35,18 +32,18 @@ We have put together a [Docker container](https://hub.docker.com/r/openworm/open ### Pre-requisites -1. You should have at least 60 GB of free space on your machine and at least 2GB of RAM. -2. You should be able to clone git repositories on your machine. [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), or [this GUI](https://desktop.github.com/) may be useful. +1. At least 60 GB of free space on your machine and at least 2GB of RAM. +2. Ability to clone git repositories on your machine. [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), or use [this GUI](https://desktop.github.com/). ### To Install -1. Install [Docker](http://docker.com) on your system. -2. If your system does not have enough free space, you can use an external hard disk. On MacOS X, the location for image storage can be specified in the [Advanced Tab](https://forums.docker.com/t/change-docker-image-directory-for-mac/18891/15) in Preferences. See [this thread](https://forums.docker.com/t/how-do-i-change-the-docker-image-installation-directory/1169/18) in addition for Linux instructions. +1. Install [Docker](http://docker.com) on your system. +2. If your system does not have enough free space, you can use an external hard disk. On MacOS X, the location for image storage can be specified in the [Advanced Tab](https://forums.docker.com/t/change-docker-image-directory-for-mac/18891/15) in Preferences. See [this thread](https://forums.docker.com/t/how-do-i-change-the-docker-image-installation-directory/1169/18) for Linux instructions. ## Running 1. Ensure the Docker daemon is running in the background (on MacOS/Windows there should be an icon with the Docker whale logo showing in the menu bar/system tray). -2. Open a terminal and run: +2. Open a terminal and run: ```bash git clone http://github.com/openworm/openworm cd openworm @@ -63,26 +60,26 @@ We have put together a [Docker container](https://hub.docker.com/r/openworm/open - `-d [num]`: Use to modify the duration of the simulation in milliseconds. Default is 15. Use 5000 to run for time to make the full movie above (i.e. 5 seconds). -### Other things to try +### Other Things to Try - Open a terminal and run `./run-shell-only.sh` (or `run-shell-only.cmd` on Windows). This will let you log into the container before it has run `master_openworm.py`. From here you can inspect the internals of the various checked out code bases and installed systems and modify things. Afterwards, you'll still need to run `./stop.sh` to clean up. - If you wish to modify what gets installed, you should modify `Dockerfile`. If you want to modify what runs, you should modify `master_openworm.py`. Either way you will need to run `build.sh` in order to rebuild the image locally. Afterwards, you can run normally. ## FAQ -#### **What is the Docker container?** +### What is the Docker container? -The Docker container is a self-contained environment in which you can run OpenWorm simulations. It's fully set up to get you started by following the steps above. At the moment, it runs simulations and produces visualizations for you, but these visualizations must be viewed outside of the Docker container. While you do not need to know much about Docker to use OpenWorm, if you are planning on working extensively with the platform, you may benefit from understanding some basics. [Docker Curriculum](https://docker-curriculum.com) is an excellent tutorial for beginners that is straightforward to work through (Sections 1 - 2.5 are plenty sufficient). +The Docker container is a self-contained environment in which you can run OpenWorm simulations. It's fully set up to get you started by following the steps above. At the moment, it runs simulations and produces visualizations for you, but these visualizations must be viewed outside of the Docker container. While you do not need to know much about Docker to use OpenWorm, if you are planning on working extensively with the platform, you may benefit from understanding some basics. [Docker Curriculum](https://docker-curriculum.com) is an excellent tutorial for beginners that is straightforward to work through (Sections 1 - 2.5 are plenty sufficient). -#### **Is it possible to modify the simulation without having to run `build.sh`?** +### Is it possible to modify the simulation without having to run `build.sh`? Yes, but it is marginally more complex. The easiest way is to modify anything in the Docker container once you are inside of it - it will work just like a bash shell. If you want to modify any code in the container, you'll need to use an editor that runs in the terminal, like nano. Once you've modified something in the container, you don't need to re-build. However, if you run `stop.sh` once you exit, those changes will be gone. -#### **How do I access more data than what is already output?** +### How do I access more data than what is already output? -The simulation by default outputs only a few figures and movies to your home system (that is, outside of the Docker container). If you want to access the entire output of the simulation, you will need to copy it from the Docker container. +The simulation by default outputs only a few figures and movies to your home system (that is, outside of the Docker container). If you want to access the entire output of the simulation, you will need to copy it from the Docker container. -For example, say you want to extract the worm motion data. This is contained in the file `worm_motion_log.txt`, which is found in the `/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt`. The directory `[SPECIFIC_TIMESTAMPED_DIRECTORY]` will have a name like `C2_FW_2018_02-12_18-36-32`, and its name can be found by checking the `output` directory. This is actually the main output directory for the simulation, and contains all output, including cell modelling and worm movement. +For example, say you want to extract the worm motion data. This is contained in the file `worm_motion_log.txt`, which is found in the `/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt`. The directory `[SPECIFIC_TIMESTAMPED_DIRECTORY]` will have a name like `C2_FW_2018_02-12_18-36-32`, and its name can be found by checking the `output` directory. This is actually the main output directory for the simulation, and contains all output, including cell modelling and worm movement. Once the simulation ends and you exit the container with `exit`, but before you run `stop.sh`, run the following command from the openworm-docker-master folder: @@ -92,13 +89,13 @@ docker cp openworm:/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTO This will copy the file from the Docker container, whose default name is `openworm`. **It is crucial that you do not run `stop.sh` before trying to get your data out (see below)** -#### **What is the difference between `exit` and `stop.sh`?** +### What is the difference between `exit` and `stop.sh`? -When you are in the Docker Container `openworm`, and are done interacting with it, you type `exit` to return to your system's shell. This stops execution of anything in the container, and that container's status is now `Exited`. If you try to re-start the process using `run-shell-only.sh`, you will get an error saying that the container already exists. You can choose, at this point, to run `stop.sh`. Doing so will remove the container and any files associated with it, allowing you to run a new simulation. However, if you don't want to +When you are in the Docker Container `openworm`, and are done interacting with it, you type `exit` to return to your system's shell. This stops execution of anything in the container, and that container's status is now `Exited`. If you try to re-start the process using `run-shell-only.sh`, you will get an error saying that the container already exists. You can choose, at this point, to run `stop.sh`. Doing so will remove the container and any files associated with it, allowing you to run a new simulation. However, if you don't want - remove that container, you will instead want to re-enter it. + to remove that container, you will instead want to re-enter it. -#### **How do I enter a container I just exited?** +### How do I enter a container I just exited? If you run `stop.sh` you'll delete your data and reset the container for a new run. If, however, you don't want to do that, you can re-enter the Docker container like this: @@ -118,4 +115,4 @@ To find out more about OpenWorm, please see the documentation at [http://docs.op This repository also contains project-wide tracking via high-level [issues](https://github.com/openworm/OpenWorm/issues) and [milestones](https://github.com/openworm/OpenWorm/milestones). ``` -You can now save this updated `README.md` file, commit it to your local repository, push to your fork, and then create a pull request to contribute to the OpenWorm project. \ No newline at end of file +This updated `README.md` file should provide clearer instructions and additional context for users, making it easier to get started with and effectively use the OpenWorm simulation. You can now follow the steps to commit and push these changes to your fork and create a pull request. \ No newline at end of file From ad9e37f7d51711b5e914c4d772d4422ff759517d Mon Sep 17 00:00:00 2001 From: Syed Hussain Ather Date: Thu, 6 Jun 2024 09:55:22 -0400 Subject: [PATCH 05/12] updated with clarity --- README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/README.md b/README.md index d36ab32..b11721e 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,4 @@ You'll be able to interact with the container as before. To find out more about OpenWorm, please see the documentation at [http://docs.openworm.org](http://docs.openworm.org) or [join us on Slack](http://bit.ly/OpenWormVolunteer). -This repository also contains project-wide tracking via high-level [issues](https://github.com/openworm/OpenWorm/issues) and [milestones](https://github.com/openworm/OpenWorm/milestones). -``` - -This updated `README.md` file should provide clearer instructions and additional context for users, making it easier to get started with and effectively use the OpenWorm simulation. You can now follow the steps to commit and push these changes to your fork and create a pull request. \ No newline at end of file +This repository also contains project-wide tracking via high-level [issues](https://github.com/openworm/OpenWorm/issues) and [milestones](https://github.com/openworm/OpenWorm/milestones). \ No newline at end of file From d670b761431c68fd9747ddb405ae8da8bddbcfd5 Mon Sep 17 00:00:00 2001 From: pikid <130920237+pikid@users.noreply.github.com> Date: Wed, 12 Jun 2024 22:37:35 +0800 Subject: [PATCH 06/12] Update Dockerfile fix bugs: 1.[ 9/28] RUN pip3 install neuron==8.0.1: 0.252 WARNING: The directory '/home/ow/.cache/pip' or its parent directory is not owned or is not writable by the current user. The cache has been disabled. Check the permissions and owner of that directory. If executing pip with sudo, you should use sudo's -H flag. 1.575 ERROR: Could not find a version that satisfies the requirement neuron==8.0.1 (from versions: 8.1a0, 8.1.0, 8.2, 8.2.1, 8.2.2, 8.2.3, 8.2.4) 1.576 ERROR: No matching distribution found for neuron==8.0.1 2.ERROR: Could not find a version that satisfies the requirement neuron==8.0.1 (from versions: 8.1a0, 8.1.0, 8.2, 8.2.1, 8.2.2, 8.2.3, 8.2.4) --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 1a4bf89..772fc93 100644 --- a/Dockerfile +++ b/Dockerfile @@ -52,7 +52,7 @@ RUN sudo update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 10 ################################################################################ ######## Install NEURON simulator -RUN pip3 install neuron==8.0.1 +RUN sudo pip3 install neuron==8.1.0 ################################################################################ From a0fc641f90000f47efab839d6674cc44dc26c1c2 Mon Sep 17 00:00:00 2001 From: KaanS139 Date: Mon, 24 Jun 2024 11:00:13 +0100 Subject: [PATCH 07/12] added PowerShell link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6a6df24..fd4322d 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ in addition for Linux instructions. 1. Ensure the Docker daemon is running in the background (on MacOS/Windows there should be an icon with the Docker whale logo showing in the menu bar/system tray). 2. Open a terminal and run: `git clone http://github.com/openworm/openworm`; `cd openworm` -3. Optional: Run `./build.sh` (or `build.cmd` on Windows). If you skip this step, it will download the latest released Docker image from the [OpenWorm Docker hub](https://hub.docker.com/r/openworm/openworm). +3. Optional: Run `./build.sh` (or `build.cmd` on Windows or '.\build.cmd' on [PowerShell](https://learn.microsoft.com/en-us/powershell/)). If you skip this step, it will download the latest released Docker image from the [OpenWorm Docker hub](https://hub.docker.com/r/openworm/openworm). 4. Run `./run.sh` (or `run.cmd` on Windows). 5. About 5-10 minutes of output will display on the screen as the steps run. 6. The simulation will end. Run `stop.sh` (`stop.cmd` on Windows) on your system to clean up the running container. From 14a500dc1c1224191e3e3bc1755c172606f4b1b5 Mon Sep 17 00:00:00 2001 From: KaanS139 Date: Mon, 24 Jun 2024 11:21:07 +0100 Subject: [PATCH 08/12] Including PowerShell instructions --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b11721e..16fc802 100644 --- a/README.md +++ b/README.md @@ -48,10 +48,10 @@ We have put together a [Docker container](https://hub.docker.com/r/openworm/open git clone http://github.com/openworm/openworm cd openworm ``` -3. Optional: Run `./build.sh` (or `build.cmd` on Windows). If you skip this step, it will download the latest released Docker image from the [OpenWorm Docker hub](https://hub.docker.com/r/openworm/openworm). -4. Run `./run.sh` (or `run.cmd` on Windows). +3. Optional: Run `./build.sh` (`build.cmd` on Windows or `.\build.cmd` on [PowerShell](https://learn.microsoft.com/en-us/powershell/dsc/overview?view=dsc-2.0)). If you skip this step, it will download the latest released Docker image from the [OpenWorm Docker hub](https://hub.docker.com/r/openworm/openworm). +4. Run `./run.sh` (`run.cmd` on Windows or `.\run.cmd` in PowerShell). 5. About 5-10 minutes of output will display on the screen as the steps run. -6. The simulation will end. Run `stop.sh` (`stop.cmd` on Windows) on your system to clean up the running container. +6. The simulation will end. Run `stop.sh` (`stop.cmd` on Windows or `.\stop.cmd` in PowerShell) on your system to clean up the running container. 7. Inspect the output in the `output` directory on your local machine. ## Advanced From 77c22a1df4d744b3af5c5eb7a69cadc077075776 Mon Sep 17 00:00:00 2001 From: pgleeson Date: Mon, 24 Jun 2024 11:51:33 +0100 Subject: [PATCH 09/12] Revert to previous version of neuron for intel also --- Dockerfile_intel | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile_intel b/Dockerfile_intel index bc26131..a9b027d 100644 --- a/Dockerfile_intel +++ b/Dockerfile_intel @@ -53,7 +53,7 @@ RUN sudo update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 10 ################################################################################ ######## Install NEURON simulator -RUN pip3 install neuron==8.2.2 +RUN pip3 install neuron==8.0.1 ################################################################################ From 2d0343a9a7b0dc150f618e94895512826d59ddd0 Mon Sep 17 00:00:00 2001 From: KaanS139 Date: Mon, 24 Jun 2024 12:03:53 +0100 Subject: [PATCH 10/12] More PowerShell updates --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 16fc802..7c06e6a 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ We have put together a [Docker container](https://hub.docker.com/r/openworm/open ### Other Things to Try -- Open a terminal and run `./run-shell-only.sh` (or `run-shell-only.cmd` on Windows). This will let you log into the container before it has run `master_openworm.py`. From here you can inspect the internals of the various checked out code bases and installed systems and modify things. Afterwards, you'll still need to run `./stop.sh` to clean up. +- Open a terminal and run `./run-shell-only.sh` (`run-shell-only.cmd` on Windows or `.\run-shell-only.cmd` in PowerShell). This will let you log into the container before it has run `master_openworm.py`. From here you can inspect the internals of the various checked out code bases and installed systems and modify things. Afterwards, you'll still need to run `./stop.sh` to clean up. - If you wish to modify what gets installed, you should modify `Dockerfile`. If you want to modify what runs, you should modify `master_openworm.py`. Either way you will need to run `build.sh` in order to rebuild the image locally. Afterwards, you can run normally. ## FAQ From cb7b164b7d346f29b0b0b9f52c2bb7022910c180 Mon Sep 17 00:00:00 2001 From: KaanS139 Date: Mon, 24 Jun 2024 13:38:30 +0100 Subject: [PATCH 11/12] add space for testing --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7c06e6a..ac7d595 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ We have put together a [Docker container](https://hub.docker.com/r/openworm/open ## Running -1. Ensure the Docker daemon is running in the background (on MacOS/Windows there should be an icon with the Docker whale logo showing in the menu bar/system tray). +1. Ensure the Docker daemon is running in the background (on MacOS/Windows there should be an icon with the Docker whale logo showing in the menu bar/system tray). 2. Open a terminal and run: ```bash git clone http://github.com/openworm/openworm From 9d678beb091a4d1b05d3da859173c1f48a7c237e Mon Sep 17 00:00:00 2001 From: pgleeson Date: Mon, 28 Oct 2024 13:18:50 +0000 Subject: [PATCH 12/12] Auto-detect arm platform in build.sh & rebuild.sh From https://github.com/openworm/OpenWorm/pull/355 --- build.sh | 12 +++++++++++- rebuild.sh | 12 +++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/build.sh b/build.sh index 4ab0e61..1481427 100755 --- a/build.sh +++ b/build.sh @@ -1,4 +1,14 @@ #!/bin/bash version=$(