How to set up 3DNA on Windows

[xiangjun]

3DNA v2.3 and previous versions contain a suite of programs, and associated data files. Setting up 3DNA is intended to be a simple process for those with command-line experience: it entails creating an environment variable named X3DNA to point to where 3DNA is stored, and an updated PATH that includes the $X3DNA/bin directory. The whole process is facilitated by a Ruby script, x3dna_setup, and should take no more than a few minutes.

With Linux and Mac OS, setting up 3DNA has normally not been an issue. For Windows, however, the situation is more complicated than desired. Cygwin or MinGW/MSYS is the preferred way to run 3DNA on Windows, but each requires the installation of a big package and the ending environment is not familiar to Windows users. By far, the most frequent and longest threads on the Forum are on how to properly set up 3DNA on Windows, initiated by new users who have no experience in command-line interface.

As of 3DNA v2.3.1-2017jun24, the compiled .exe files in the tarball x3dna-v2.3-mingw-win.tar.gz should run in native Windows (i.e. without Cygwin or MinGW/MSYS) via the command prompt. However, the default Windows command prompt (cmd.exe) is a dinosaur and awkward to use. I played with Windows PowerShell a bit, but it gave some surprises with processing of command-line options. The win-bash shell may be a choice, or one can install Bash on Windows 10.

In the long run, when the 'Bash on Windows' becomes a default, the whole issue of setting 3DNA will on longer exist any more. In the meantime, this FAQ entry provides detailed instruction on how to set up 3DNA v2.3 on native Windows (tested on Windows 7).

• Install ConEmu (Stable, Installer) -- it is far superior to Windows cmd.exe
  

  ConEmu-Maximus5 is a Windows console emulator with tabs, which presents multiple consoles and simple GUI applications as one customizable GUI window with various features...file and archive management, command history and completion, powerful editor.
• Download the Windows version of 3DNA v2.3, the x3dna-v2.3.zip file (Note that you need to register and log in to see the download link). The zip file normally ends up in the Downloads/ folder under your home folder (e.g., C:\Users\xiangjun\Downloads.)
• Right-click the x3dna-v2.3.zip file, in the context menu select "Extract All...". In the setting window, you can select the folder under which 3DNA will be installed. Please do not specify x3dna-v2.3 explicitly in setting the folder, since x3dna-v2.3 will always be appended to it.
  
  In principle, you can install 3DNA anywhere. It is a good choice to put it directly under your home folder (e.g., C:\Users\xiangjun). See the screenshot below.
  
  
  
  Click the "Extract" button at the bottom right. You'll see lots of files being extracted. Take a note of the 3DNA folder (i.e., C:\Users\xiangjun\x3dna-v2.3\ as shown above) as this information is needed next.
  
  Navigate to the designated 3DNA folder and make sure it has the content shown below. Right-click on file license.txt and select "Properties". The Location: field should report its parent folder (no ending slash) that agrees with the one shown above.
  
  
  
  
• Set the X3DNA environment variable and update the PATH. See "How to set the path and environment variables in Windows" for details. Here I am using Windows 7 as an example.
  
  
  • From the "Desktop", right-click the "Computer" icon and select "Properties". If you don't have a Computer icon on your desktop, click the "Start" button, right-click the "Computer" option in the Start Menu, and select "Properties".
  • Click the "Advanced System Settings" link in the left column.
  • In the System Properties window, click on the "Advanced" tab, then click the "Environment Variables..." button near the bottom of that tab.
  • In the Environment Variables window, the top part is for User variables (for xiangjun in the example). Click the "New..." button, and you will see the New User Variable window. For the Variable name text field, type X3DNA, and for Variable value, type C:\Users\xiangjun\x3dna-v2.3\ (with ending slash). Note that this value must match what is specified in the extraction step, i.e., pointing to where 3DNA is actually installed. See the following screenshot.
    
    
    
    Click the "OK" button, and the result is as shown below:
    
    
  • In the Environment Variables window, the bottom part is for System variables. Scroll to find the Path variable, which contains a long list of values separated by semicolon (e.g. C:\Windows\system32;...). Highlight (select) the Path entry and click the "Edit..." button. The Edit System Variable window will appear. The Variable name text field will be Path. Scroll to the end of Variable value, add ;C:\Users\xiangjun\x3dna-v2.3\bin. Note that each different directory is separated with a semicolon. See screenshot below.
    
    
• Now double-click the ConEmu icon on the desktop to open a new terminal window. Type find_pair -h in the command prompt, you should see a result screen as shown below.
  
  
• Optionally, install Ruby on Windows. You may skip this step when you just get started with 3DNA on Windows. The Ruby scripts distributed with 3DNA v2.3 are mostly for generating schematic block images, and analyzing NMR ensembles.
  
  Do not forget to click the check box "Add Ruby executables to your PATH". See the first entry in Troubleshooting.
  
  
  
  Note that at the end of the installation, you do not need to click the checkbox to install "MSYS2 and development toolchain". 3DNA v2.3 runs just fine as is, even though getting them installed does not hurt.
  

If you notice any problem, please post below with details.

[Hari Seldon]

I installed on Windows and got to the end just fine until find_pair -h

linux@DESKTOP-JS6SA18 C:\Users\linux
> find_pair -h
'find_pair' is not recognized as an internal or external command,
operable program or batch file.

I also tried installing 3DNA On Linux (including Mac OS X, or Cygwin on Windows)
http://forum.x3dna.org/howtos/how-to-install-3dna-on-linux-and-windows/

And it all worked until find_pair -h

linux@DESKTOP-JS6SA18 /cygdrive/d/Documents/NYU/Projects/Gunsalus/Code/3DNA/Linux/x3dna-v2.3/bin
$ ./find_pair -h
-bash: ./find_pair: cannot execute binary file: Exec format error

[xiangjun]

> find_pair -h
'find_pair' is not recognized as an internal or external command,
operable program or batch file.

The error message means that the PATH is not set properly. Probably the X3DNA environment variable is not set correctly either.

I've just finished the FAQ, with corrections with initial draft versions. You may be following an early version of the post. Could you please try again, following the steps, and report back if it works? Please use screenshot as necessary.

Also, what Windows version are you using?

Best regards,

Xiang-Jun

[Hari Seldon]

I am using Windows 10.

Download ConEmu Stable, Installer (32-bit, 64-bit) - 5.23 MB | version: 161206 | File Signatures



Ruby 2.4.1-2 (x64)



RubyInstaller2



Download the Windows version of 3DNA v2.3, the x3dna-v2.3.zip file





Set the X3DNA environment variable and update the PATH

[xiangjun]

Thanks for the detailed screenshots. It is weird. Things should not be that hard. Let's work together to sort things out.

Could you please do the following:

• Within ConEmu terminal, type: echo %X3DNA%
• On my case, the output is: C:\Users\xiangjun\x3dna-v2.3\, as originally set.

What's your output?

Xiang-Jun

[Hari Seldon]

Microsoft Windows [Version 10.0.15063]

linux@DESKTOP-JS6SA18 C:\Users\linux
> echo %X3DNA%
D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\x3dna-v2.3\

linux@DESKTOP-JS6SA18 C:\Users\linux
>

[xiangjun]

The X3DNA environment variable looks right. The problem could be due to missing the %X3DNA%\bin folder in PATH.

To verify, what the output from running the following commands (in ConEmu terminal):

Code: [Select]

dir %X3DNA%\bin
%X3DNA%\bin\find_pair
Xiang-Jun

[Hari Seldon]

Microsoft Windows [Version 10.0.15063]

linux@DESKTOP-JS6SA18 C:\Users\linux
> dir %X3DNA%\bin
 Volume in drive D is DATA
 Volume Serial Number is 1A46-D28D

 Directory of D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\x3dna-v2.3\bin

06/24/2017  11:47 AM    <DIR>          .
06/24/2017  11:47 AM    <DIR>          ..
               0 File(s)              0 bytes
               2 Dir(s)  395,301,408,768 bytes free

linux@DESKTOP-JS6SA18 C:\Users\linux
> %X3DNA%\bin\find_pair
'D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\x3dna-v2.3\\bin\find_pair' is not recognized as an internal or external command,
operable program or batch file.

[xiangjun]

From your previous reply,

Code: [Select]

> echo %X3DNA%
D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\x3dna-v2.3\
Now you've

Code: [Select]

> dir %X3DNA%\bin
 Volume in drive D is DATA
 Volume Serial Number is 1A46-D28D

 Directory of D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\x3dna-v2.3\bin

06/24/2017  11:47 AM    <DIR>          .
06/24/2017  11:47 AM    <DIR>          ..
               0 File(s)              0 bytes
               2 Dir(s)  395,301,408,768 bytes free
This is UNEXPECTED -- "0 File(s)" within %X3DNA%\bin.

The dir %X3DNA%\bin command should list the 3DNA executable files in directory "D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\x3dna-v2.3\bin", as shown below in my case.

Could you do the following, to make sure you have 3DNA installed in the folder:

Code: [Select]

    REM this command should change you to the 3DNA directory --- this is a REMark (comment line)
cd %X3DNA%

    REM this command lists the content of the folder (%X3DNA%)
dir

    REM this command lists content of the examples folder within 3DNA
dir examples
Best regards,

Xiang-Jun

[Hari Seldon]

I needed to re-extract x3dna-v2.3.zip because at first I just hit the extract button on the zip file then it creates D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\x3dna-v2.3\x3dna-v2.3 and then I copied and pasted the x3dna-v2.3 folder into D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\ to get rid of the duplicate x3dna-v2.3.  That extraction and copy-paste created empty directories somehow.

What worked was not extracting at all and just entering the zip file and cut and pasting the x3dna-v2.3 folder from the zip file into D:\Documents\NYU\Projects\Gunsalus\Code\3DNA\.  After that find_pair -h works (see below), however there was a strange message I got while cut and pasting



I let the files overwrite.



Microsoft Windows [Version 10.0.15063]

linux@DESKTOP-JS6SA18 C:\Users\linux
> find_pair -h
===========================================================================
NAME
        find_pair - locate base-pairs and helical regions
SYNOPSIS
        find_pair [OPTION] PDBFILE OUTFILE
DESCRIPTION
        locate base-pairs and helical regions given a PDB data file. Its
        output can be directly fed into analyze, cehs and Lavery's Curves
        program.
        -s, -1  treat the whole structure as a continuous single helix.
                Useful for getting all backbone torsion angles
        -c      get Curves input for a duplex
        -c+     get input for Curves+ (duplex, ATOM records only)
        -d      generate a separate output file for each helical region
        -p      find all base-pairs and higher-order base associations
        -a      read in only the ATOM records, ignoring HETATM records
        -z      more detailed base-pairing information in the output
        -h      this help message (any non-recognized options will do)
INPUT
        PDB data file
        One-letter options can be in either case, any order and combined
EXAMPLES
        find_pair sample.pdb sample.inp
        find_pair -p sample.pdb allbp_list
        find_pair -c+ sample.pdb sample_c+.inp
                  [then run: Cur+ < sample_c+.inp]
OUTPUT
        base-pair listing for input to analyze, cehs and Curves
        bestpairs.pdb, hel_regions.pdb, col_chains.scr, col_helices.scr
        allpairs.pdb, multiplets.pdb, mulbp.inp
SEE ALSO
        analyze, cehs, anyhelix, ex_str, stack2img
AUTHOR
        3DNA v2.3.1-2017jun24, created and maintained by Xiang-Jun Lu (PhD)

Please post questions/comments on the 3DNA Forum: http://forum.x3dna.org/
Please check 'http://x3dna.org/citations' on how to cite 3DNA --- THANKS!
===========================================================================

linux@DESKTOP-JS6SA18 C:\Users\linux
>

[xiangjun]

Glad to see things work out. The repeated folder name, ...\x3dna-v2.3\x3dna-v2.3, was due to the following two factors:

• When x3dna-v2.3.zip is extracted, the \x3dna-v2.3 folder is automatically appended.
• The "Extract All..." command, showing up when right-click on x3dna-v2.3.zip, will set the default folder with \x3dna-v2.3 at its last element: e.g., C:\Users\xiangjun\Downloads\x3dna-v2.3, as in my case.
  

I noticed this caveat while testing, but before finishing the FAQ entry. You were quick in following the original unpolished content... I've thereafter added a note to remind users to removing the \x3dna-v2.3 portion from the "Extract All..." default setting.

The double \x3dna-v2.3 folder name is actually not a big deal (just looking ugly), once one knows it -- the X3DNA environment variable simply needs to be adjusted accordingly.

Instead of right-click on x3dna-v2.3.zip and then ""Extract All...", one can simply double-click x3dna-v2.3.zip. This will create a \x3dna-v2.3 folder on par with the x3dna-v2.3.zip file. Then one can drag-and-drop the resultant \x3dna-v2.3 folder to a desired location.

Also, the X3DNA environment variable can be set directly in ConEmu terminal. And the PATH can be updated via command line as well. Once one knows the basics, the setting up process can be performed in numerous ways, and be finished in no more than a few minutes.

Xiang-Jun

[xiaoxuesheng]

Dear XiangJun,
I've configured the environment variables and they're correct, but there won't be ConEmu, and I don't know the basic problem of how ConEmu imports a PDB file.
Can you give me a tutorial on how to use it? Do you have a visual action window, if any, where to use it?
I'm using windows.Thanks.

[xiangjun]

Hi,

You do not need ConEmu to run 3DNA, even though ConEmu is a much better command-line interface than the native cmd.exe on Windows. Moreover, ConEmu has nothing to do with importing PDB files.

Please follow the steps and show us where you got stuck, preferrable with screenshots.

Best regards,

Xiang-Jun

[Beñat Olave]

Hello, I think there is an error with the update of today:

Benat@SURFACE-OLAVE C:\Users\Benat
$ find_pair -h
open_file <C:\Users\Benat\x3dna-v2.3config/version> failed: No such file or directory

Best regards and thanks for your effort.

[xiangjun]

Hi,

Thanks for reporting. What's the output (or the setting) of your $X3DNA? Did you set it up explicitly? Adding the end slash should do the trick.

I've just tested the new release on Msys2 with Windows 7, and the programs work as expected. There could be some edge cases that need to be taken care of.

Best regards,

Xiang-Jun

[xiangjun]

As a follow-up, I've just re-installed 3DNA Windows (x3dna-v2.3.zip) in native Windows environment. I'm convinced that if you added the end slash in your setting of the X3DNA environment variable, as noted in step 4.4 (with the screenshot linked below), 3DNA would work as expected. Please have a try and report back your findings.



Thanks,

Xiang-Jun

[Beñat Olave]

Hello,

I did it in windows 10 and I think I put everything okay (I followed all the steps presented here with ConEmu):

The output is:
"C:\Users\Benat\x3dna-v2.3\"

I fixed it creating just another folder for config with the name of "x3dna-v2.3config"

I am just learning how to use the program, I have another issue that I will post in bug reports (but probably is my fault)

Edited: Maybe the .zip you tested is not the same as the uploaded one? And that's why there is something missing?

[xiangjun]

Thanks for reporting back. I'm surprised to see that with ending slash you could (still) have the originally reported problem. With ConEmu, could you please post back the output of the following commands, preferably with a screenshot?

Code: [Select]

echo %X3DNA%
echo %PATH%
I'm glad to see your smart workaround by creating a x3dna-v2.3config folder.

Thanks,

Xiang-Jun

[Beñat Olave]

Hello, here is the image

[xiangjun]

Great! Please do the following, and report back with a screenshot:

Code: [Select]

dir %X3DNA%config\version
Thanks,

Xiang-Jun

[Beñat Olave]

Hello, it says:

"
$ dir %X3DNA%config\version
The volume of unit C has no label.
The serial number of the volume is: A2CF-EF3C
Directory of C:\Users\Benat\x3dna-v2.3\config
05/11/2018  22:15                68 version
               1 file                68 bytes
               0 dirs  101.483.311.104 free bytes
"

[xiangjun]

Thanks --- the output result is as expected. Then 3DNA should work with the original config folder, without creating a new x3dna-v2.3config folder. Yours is the first reported 'weird' case. Let's see if other 3DNA users have a similar problem in the future.

Best regards,

Xiang-Jun

[wei tian]

Dear Dr.Xiangjun:

I have tried to download the software of 3DNA with versions of both V2.4.0 and v2.3.4, and then extract all the folders from the zip file,but I can't find license.txt file.So, I can't install the software successfully, can you tell me some reasons for this problem?

[xiangjun]

You do not need 'license.txt' to get 3DNA v2.4.0 (or v2.3.4) up and running.

What do you mean that you "install the software successfully"? Please provide details, better with screenshots to show the problem you face unambiguously.

Best regards,

Xiang-Jun