0.3.0 is a major, package-wide refactorization

shaharkadmiel commented 8 years ago

Modules were reorganized into 5 subpackages:

cli - provides some command line interface scripts. I want to create more of those for easy quick-and-dirty plotting from the command line. This is useful because the user can easily wrap those in a cronjob for plotting of the last timestep that was written to disk during run-time for previewing the solution.
plotting - now has more plotting related modules and utils but can and should probably be improved in the future, especially the image.py and waveforms.py modules that do batch plotting for an entire SW4 directory.
postp - previously this was core. I thought postp is more suitable as this is actually used for postprocessing, reading and plotting images and waveforms. Although important, it is definitely not the core of the package.
prep - previously was called preprocess. made it shorter to stay in the same line of style as postp. This subpackage has modules mainly used in the simulation setup phase. The rfileIO module has routines for reading and writing rfile models. the material_model module has routines for assisting the user when prescribing the material properties of the model. stations module helps place single rec stations, stations on a line or in an array.
utils - has some useful utilities such as convenient wrappers for calculating the Fourier spectrum or the PSDE of a signal, resampling of grids, reading and writing GeoTIFF files for DEM plotting and other useful reprojection tools.

I am currently setting up some examples that will serve as a tutorial and a gallery. The readme page can be replaced with something more informative for installing and basic usage but should reference the docs as those are more comprehensive.

megies commented 8 years ago

You/we should do a proper fixed version 0.2.? release, tagged at github (and/or even pushed to pypi) before merging this one..

shaharkadmiel commented 8 years ago

@megies , not sure what you mean... Are you saying I should fix code in place with the current structure of 0.2.0 (core, preprocess, plotting, ...) before merging? why? I'd rather get v0.3 out with full documentation and examples (working in those...).

About PyPI, I agree but will need your help...

megies commented 8 years ago

Currently, regardless of what commit from the current master branch you install (e.g. pip install https://github.com/shaharkadmiel/pySW4/archive/master.zip or pip install https://github.com/shaharkadmiel/pySW4/archive/d0edc7f7db2f61654b197f0c49c59a809d15302a.zip, your python console will tell you: version = 0.2.0..

$ python -c 'import pySW4; print(pySW4.__version__)'
0.2.0

So, the version number right now is not very reliable. Compare e.g. https://github.com/FDSN/StationXML/commit/61fa828129eb50cb2a29599bd829116e84fa5ec2 and https://github.com/FDSN/StationXML/pull/3#issuecomment-196358969 and following comments.

When the version number is hard coded in the code base it might be best to have something like "dev" or "0.0.0" in there and manually bump it for releases (e.g. by doing a one-commit branch off of master just for the release).

Edit: pypi is not so important right now probably.. With conda-forge it's actually super simple to get proper versions into Anaconda cloud (for installation with conda install), even less work than maintaining the package with a source distribution at pypi..

shaharkadmiel commented 8 years ago

Okay... so you are suggesting I change the hard coded version in master to say "dev"? Either way, why would that matter once v0.3 is released?

I apologize for the dumb questions, just don't really know the "rules and habits" of software development. Learning on the fly...

megies commented 8 years ago

No problem at all. It's just that right the version number displayed to users is not meaningful.. it does not say much about what state of the package is really installed. I'll do a demo...

megies commented 8 years ago

So, on current master I changed the hard coded version number in the code base to 0.0.0.dev. This makes it clear to everybody who installs from a "dirty" state (i.e. not a release version state) of the code base that it's not a well defined release but rather some developer snapshot of the repo that is installed. It also makes sure that any well-defined release versions of the package will be preferred by e.g. pip or conda.

For doing a release one can make a dedicated release branch with a single commit and tag this state on github and label it as a proper release.

See...

https://github.com/shaharkadmiel/pySW4/commit/8a60881f4093dac4e8e5c619f6c5bc7d1fb47cc7

https://github.com/shaharkadmiel/pySW4/branches https://github.com/shaharkadmiel/pySW4/commit/631ed3837c122f5b1a6553ca85fed9695272d26e

https://github.com/shaharkadmiel/pySW4/releases

Of course that's just one way to handle release version.. it's just a recommendation with a simple approach. In any case, I think that the master branch should not hold a version number that implies a fixed release..

shaharkadmiel commented 8 years ago

Got it... how do we push to PyPI?

megies commented 8 years ago

This looks like a good and concise explanation: http://peterdowns.com/posts/first-time-with-pypi.html

Edit: Want me to create the package on PyPi and try a first upload?

shaharkadmiel commented 8 years ago

Thank you @megies , Looks good indeed. So do you think I should do this fo v0.2.1 and then again for v0.3?

megies commented 8 years ago

So do you think I should do this fo v0.2.1 and then again for v0.3?

Putting the stuff on pypi is just some additional convenience step for users. I think just referring to the github releases page and stating "do pip install https://github.com/shaharkadmiel/pySW4/archive/0.2.1.zip" in installation instructions is fine, too. Depends whether you want to go the extra distance.. ;-)

Are you (and people you know, or people you know might want to use pySW4) using Anaconda/conda? Like I mentioned, with conda-forge it would be super-simple to get pySW4 conda packages into the conda-forge channel. People could do something like $ conda install -c conda-forge pySW4 in that case..

megies commented 8 years ago

@shaharkadmiel I registered pySW4 on pypi and uploaded an initial release 0.2.2.

You can do the same in the future with..

put your pypi login/credentials in ~/.pypirc
install twine (e.g. conda install twine)

$ # go to pySW4 root dir with setup.py in it
$ # do a release branch and bump to correct version number in __init__.py and commit it
$ # I usually do a "git clean -fdx" but this might be paranoid, BEWARE this would remove any local changes, so in general use a clean checkout of the repo for this
$ umask 0022 && chmod -R a+rX . && python setup.py sdist --format=zip
$ twine upload -r pypitest dist/pySW4-0.2.2.zip  # test uploading to testpypi service, optional
$ twine upload dist/pySW4-0.2.2.zip

Edit: Let me know when you made a pypi user account, so I can add you as an owner of pySW4 on pypi..

shaharkadmiel commented 8 years ago

Thanks @megies ! My pypi username is shaharkadmiel (also on pypitest).

megies commented 8 years ago

Ok, done (for both pypi and testpypi)!

megies commented 7 years ago

prep - previously was called preprocess

In general I like full explicit names better (my favorite would even be preprocessing, but then again, no big thing, so your call.

...
Explicit is better than implicit.
...
Readability counts.
...

;-)

shaharkadmiel / pySW4

0.3.0 is a major, package-wide refactorization #7